NetAcquire Protocol Reference

This document provides detailed specifications of the NetAcquire program's communication protocol. This information can be used to write alternate Acquire playing programs that are compatible with NetAcquire. This includes both end-user programs and bots that are written to automatically play the game.

Table of Contents

1. About This Document
2. Communication Protocol
1. General Format
2. Handshake
3. Common Parameters
1. Chain-ID
2. Client-State-ID
3. End-Game-Flag
4. Game-Status-ID
5. Message-Text
6. Rack-Tile
7. Tile-ID
8. Tile-State
9. Version-ID
4. Host-Processed Directives
1. BM - Broadcast Message
2. CL - Close Client
3. CS - Chain Selected
4. GS - Game State
5. JG - Join Game
6. LG - List Games
7. LU - List Users
8. LV - Leave Game
9. MD - Merger Disposition
10. P - Purchase
11. PG - Start Game Play
12. PI - Ping (host)
13. PL - Add Player
14. PR - Ping Response (host)
15. PT - Play Tile
16. SG - Start Game
5. Client-Processed Directives
1. AT - Activate Tile
2. GC - Get Chain
3. GD - Get Disposition
4. GM - Game Message
5. GP - Get Purchase
6. GT - Get Tile
7. LM - Lobby Message
8. M - Client Message
9. PI - Ping (client)
10. PR - Ping Response (client)
11. SB - Set Board Status
12. SP - Start Player
13. SS - Set State
14. SV - Set Value
3. Document History
4. Suggestions for Improvement

About This Document

This document was originally compiled by Kensit (lornic at telus dot net). Any inquiries about the protocol structure or general contents of this document should go to him. In the process of making a compatible client, this document was updated, prettied and fleshed out by Nolan Waite (nolan at nwaite dot com). Any inquiries about the look of the document—typos, formatting issues and so on—should go to him.

Various editions of the board game Acquire have labeled hotel chains with various names. All known names are listed throughout this document. Names treated similarly should be considered identical by various clients (i.e. Luxor and Sackson are always the same chain).

Communication Protocol

This section defines how NetAcquire communicates and provides information on writing alternate programs that may use that protocol.

All communication between NetAcquire clients and hosts is handled via strings of data containing sets of "Directives". A directive is a single activity for NetAcquire to process. All strings are ASCII-encoded. The last character of a string of data is always a colon.

Directives conform to a General Format and are broken into Host-Processed Directives and Client-Processed Directives. Common Parameters define those parameters that have a single definition common to all uses.

Multiple directives can be sent within single blocks of data (e.g. SS;4;:SB;99,0;:). They will be separated by the string ";:".

General Format

All directives are formatted:

Directive-Code;Parameter-String;:

Where:

• Directive-Code is a 1 or 2 character identifier of the type of directive.
• Parameter-String is a string of comma-separated values used by the directive. A parameter can be enclosed in double quotation marks; if so, any character is allowed within the quotation marks (double quotation marks in the input string are escaped by doubling up). (e.g. LM;"Any way you want it;:;:;: ""Any way at all"", he said.";:) If a parameter is not so enclosed, the characters double quotation mark ("), colon (:) and semicolon (;) are not allowed.

Each directive specification notes the directive's purpose, format and notes on its values or use.

Connection Handshake

To connect to a Netacquire server, the host should send a SP - Start Player directive to the client immediately upon accepting an incoming connection. The client should respond with a PL - Add Player directive to the server. The server should then send a SS - Set State directive with the Client-State-ID of 3. The server can send some lobby messages indicating the current status of the server: number of users, number of games, etc.

Common Parameters

Chain-ID

Numeric code used to identify a hotel chain. The value used is the hexadecimal RGB specification of a hotel chain's color converted to decimal.

Client-State-ID

Numeric code used to announce to a client what state they are now entering.

End-Game-Flag

0 if game should not end; 1 if game should end. (See P - Purchase directive.)

Unknown values. (See GP - Get Purchase directive.)

Game-Status-ID

Numeric code used to identify the current state of a game.

Message-Text

ASCII text string of a user-typed message, enclosed in double quotes. Any double quotes within the message must be escaped by doubling up.

Rack-Tile

Index number identifying the entry on a player's table of held tiles, from 1-6.

Tile-ID

Integer value of a tile on the board. Tiles in column 1 (1A, 1B, etc.) are tiles 1-9; column 2, 10-18; column 3, 19-27; column 4, 28-36; column 5, 37-45; column 6, 46-54; column 7, 55-63; column 8, 64-72; column 9, 73-81; column 10, 82-90; column 11, 91-99; column 12, 100-108.

Tile-State

Integer value representing current state of the tile. Is 0 if tile is not in hotel, 12648384 if player can make a hotel with the tile, and otherwise takes on a Chain-ID to indicate the hotel it is part of.

Version-ID

Series of three parameters related to the version number. For example, "version 2.0.3" becomes the three parameters "2", "0", "3".

Host-Processed Directives

BM - Broadcast Message

• Purpose User-typed message to be sent to all relevant clients.
• Format Message-Directive, Message-Text
• Message-Directive the directive code for the client-processed message directive to be used. Is either string literal "Game Room" or "Lobby".
• Message-Text see Message-Text.
• Example BM;Lobby,"Send this message to everyone in the lobby!";:
• Notes The host builds a new directive with Message-Directive and Message-Text and then sends it to all clients (all users in the game room if GM, all users connected to host if LM), including the client who originated the BM - Broadcast Message directive.

CL - Close Client

• Purpose Requests host to drop the client connection.
• Format Reason-Text
• Reason-Text Text string enclosed in double-quotes.
• Example No example.
• Notes Apparently, the official Netacquire client reacts in this way (currently unverified): only clients who are using a user-specified port number on their local machine use this directive. This is an attempt to allow the port to be reused by the client. By having the host close the port first, the client is then able to reuse the port right away (in theory). Reason-Text is displayed in the host log if non-blank (however, it currently is never set to a non-null value by clients).

CS - Chain Selected

• Purpose Tells the host the hotel chain the player has selected for a game action (form chain, selecting merger survivor, or selecting merge chain sequence).
• Format Chain-ID, Selection-Type
• Chain-ID see Chain-ID.
• Selection-Type Game-Status-ID for the next game action to be performed due to the selection. This value is always the same as the one passed in the preceding GC - Get Chain directive.
• Example CS;255,4;:
• Notes The host proceeds with the game by using the Chain-ID to process the game action indicated by Selection-Type.

GS - Game State

• Purpose Requests host to send the client status information about the game.
• Format No parameters.
• Example GS;;:
• Notes The host sends a series of GM - Game Message directives with status information about the current game the user is in.

JG - Join Game

• Purpose Request by a client to join an existing game as a player or a spectator.
• Format Game-Number, Player-Flag
• Game-Number an integer identifying the number of the game.
• Player-Flag 0 if client wishes to observe, or -1 if client wishes to play.
• Example JG;1,-1;:
• Notes In the official Netacquire client, Game-Number is entered by the user and may not necessarily be a valid game number.

LG - List Games

• Purpose Requests host to send the client information about the currently active games.
• Format No parameters.
• Example LG;;:
• Notes The server sends the client a series of LM - Lobby Message directives for the set of currently active games.

LU - List Users

• Purpose Requests host to send the client information about the currently active users.
• Format No parameters.
• Example LU;;:
• Notes The server sends the client a series of LM - Lobby Message directives for the set of currently active users.

LV - Leave Game

• Purpose Notifies host of intention to leave the current game the client is in.
• Format No parameters.
• Example LV;;:
• Notes No notes.

MD - Merger Disposition

• Purpose Notify server of client's decision what to do with shares after a merge.
• Format Sell-Count, Trade-Count
• Sell-Count number of shares to be sold for cash.
• Trade-Count number of shares to be traded for the merger survivor's chain.
• Example MD;0,4;:
• Notes Expected response to a GD - Get Disposition directive.

P - Purchase

• Purpose Notify host how many shares of each hotel the client purchased.
• Format Luxor-Purchased, Tower-Purchased, American-Purchased, Festival-Purchased, Worldwide-Purchased, Continental-Purchased, Imperial-Purchased, End-Game-Flag
• Luxor-Purchased number of Luxor/Sackson shares purchased.
• Tower-Purchased number of Tower/Zeta shares purchased.
• American-Purchased number of American/America shares purchased.
• Festival-Purchased number of Festival/Fusion shares purchased.
• Worldwide-Purchased number of Worldwide/Hydra shares purchased.
• Continental-Purchased number of Continental/Phoenix shares purchased.
• Imperial-Purchased number of Imperial/Quantum shares purchased.
• End-Game-Flag see End-Game-Flag
• Example P;2,0,0,1,0,0,0,0;:
• Notes None of the variables are optional. The official Netacquire client does not check any variables to ensure they are reasonable.

PG - Start Game Play

• Purpose Notify host of client's desire to start the game.
• Format No parameters.
• Example PG;;:
• Notes No notes.

PI - Ping (host)

• Purpose See if host is awake.
• Format Start-Time
• Start-Time See example for time format.
• Example PI;6:08:41 PM;:
• Notes Sends immediate response of a PR - Ping Response directive to client.

PL - Add Player

• Purpose Register client's nickname and version with host.
• Format Nickname, Version-ID
• Nickname Client's desired nickname.
• Version-ID see Version-ID.
• Example PL;Champion,2,0,3;:
• Notes Sent by client immediately after receiving SP - Start Player directive as part of the Connection Handshake.

PR - Ping Response (host)

• Purpose Client's response to a host's PI - Ping directive.
• Format Ping-Start-Time
• Ping-Start-Time See example for time format.
• Example PR;6:08:41 PM;:
• Notes Unsure if Ping-Start-Time should be the time the original ping started, or the time the response was sent. This directive seems to have no in-game effect; rather, it is for the information of curious users.

PT - Play Tile

• Purpose Notify host of the tile the client wishes to play.
• Format Played-Rack-Tile
• Played-Rack-Tile the Rack-Tile for the tile the player wishes to place on the board.
• Example PT;3;:
• Notes The official Netacquire client does not check whether Played-Rack-Tile refers to a tile that can be legally played.

SG - Start Game

• Purpose Notify host of desire to create a new game.
• Format Player-Limit
• Player-Limit Integer denoting number of players allowed in the game.
• Example SG;5;:
• Notes Player-Limit should be a reasonable value, i.e. greater than one and less than 10. The board game Acquire suggests a maximum of six players; Netacquire clients should not be expected to handle more.

Client-Processed Directives

Directives sent from a host to a client, to be processed by the client.

AT - Activate Tile

• Purpose Set a rack tile's state.
• Format Rack-Tile, Tile-ID, Rack-Color
• Rack-Tile see Rack-Tile.
• Tile-ID see Tile-ID.
• Rack-Color see Chain-ID.
• Example AT;1,56,12632256;:
• Notes Receiving this directive for a tile the client doesn't have on his rack means he just drew said tile.

GC - Get Chain

• Purpose Ask client to choose a hotel from a list.
• Format Selection-Type, Hotel-Indexes
• Selection-Type Game-Status-ID for the game's next action (i.e. the one undertaken after this is processed). Limited to: 4 - Form Chain (creating a new hotel) 6 - Surviving Hotel (choosing the survivor among hotels tied in size) 8 - Get Disposition (after selecting merging chain).
• Hotel-Indexes a list of indexes indicating available hotels (1=Luxor, 2=Tower, ..., 7=Imperial)
• Example GC;4,1,2,3,5,6,7;:
• Notes The host expects the immediate response of a CS - Chain Selected directive.

GD - Get Disposition

• Purpose Ask client what he wants to do with his shares in a disappearing hotel.
• Format Merger-Flag, Chain-Name, Chain-Holding, Survivor-Shares-Available, Chain-ID, Survivor-Chain-ID
• Merger-Flag Purpose unknown. Observed value "True" when someone else merged. Observed value "False" when client merged.
• Chain-Name Name of hotel whose shares are being dealt with.
• Chain-Holding Number of shares client has in hotel.
• Survivor-Shares-Available Maximum number of shares that can be traded for.
• Chain-ID Chain-ID of hotel being dealt with (see Chain-ID).
• Survivor-Chain-ID Chain-ID of surviving hotel (see Chain-ID).
• Example GD;True,Tower,4,15,65535,16512;:
• Notes Appears to use string literals "True" and "False", not 0 and -1, for boolean values.

GM - Game Message

• Purpose Display a message in-game.
• Format Message-Text
• Message-Text The message to be displayed. See Message-Text for quoting/escaping details.
• Example GM;"Show this message in the game's chat.";:
• Notes No notes.

GP - Get Purchase

• Purpose Ask client what he would like to purchase.
• Format Game-Can-End-Flag, Cash-Available
• Game-Can-End-Flag see End-Game-Flag.
• Cash-Available The cash the client has on hand.
• Example GP;0,6000;:
• Notes Server expects eventual response of P - Purchase directive.

GT - Get Tile

• Purpose Tell client to play a tile.
• Format No parameters.
• Example GT;;:
• Notes Server expects eventual response of PT - Play Tile directive.

LM - Lobby Message

• Purpose Display a message in the lobby.
• Format Message-Text
• Message-Text The message to be displayed. See Message-Text for quoting/escaping details.
• Example LM;"Show this message in the lobby.";:
• Notes No notes.

M - Client Message

• Purpose Display message box.
• Format Client-Message-Text
• Client-Message-Text A parameter list-like string of message box options, apparently in the form Dialog-Type, Dialog-Title, Dialog-Text, enclosed in double quotes.
• Example M;"I;Game ended;The game has ended, click OK to view final game results.";:
• Notes Some announcements, such as entering Test Mode or the game being over, are only given through this directive.

PI - Ping (client)

• Purpose Initialize a ping attempt.
• Format Ping-Start-Time
• Ping-Start-Time See example for time format.
• Example PI;6:08:41 PM;:
• Notes Expects a PR - Ping Response as immediate response from client.

PR - Ping Response (client)

• Purpose Respond to host's PI - Ping directive.
• Format Ping-Start-Time, Host-Nickname
• Ping-Start-Time See example for time format.
• Host-Nickname This parameter appears absent from actual directives in the official NetAcquire client.
• Example PR;6:08:41 PM;:
• Notes Unsure if Ping-Start-Time should be the time the original ping started, or the time the response was sent. This directive seems to have no in-game effect; rather, it is for the information of curious users.

SB - Set Board Status

• Purpose Indicate that a tile's status has changed.
• Format Tile-ID, Tile-State
• Tile-ID see Tile-ID.
• Tile-State see Tile-State.
• Example SB;99,0;:
• Notes If this directive refers to a tile on a player's rack, assume that player has played the tile (i.e. take it off the rack).

SP - Start Player

• Purpose Notify client that connection is complete.
• Format Version-ID, Host-Nickname
• Version-ID see Version-ID.
• Host-Nickname The nickname of the host.
• Example SP;2,0,3,Champion;:
• Notes Part of the Connection Handshake.

SS - Set State

• Purpose Set internal state of official NetAcquire client.
• Format Client-State-ID
• Client-State-ID see Client-State-ID.
• Example SS;3;:
• Notes Part of the Connection Handshake.

SV - Set Value

• Purpose Fiddle with the user interface.
• Format Form-Name, Control-Name, Control-Index, Property-ID, Property-Value
• Form-Name string identifying the internal form name that contains the control whose property is to be set. Refer to Game Set-Values Reference for the values used.
• Control-Name
• Control-Index
• Property-ID string identifying the name of the property to be set.
• Property-Value
• Example SV;frmTileRack,cmdTile,1,Visible,0;:
• Notes The official Netacquire client sends certain information only through this directive: change in players' cash, for example. Moreover, Control-Index is particularly ill-defined.

Document History

• 2009-Jul-06 (nwaite) Added info about various names of hotel chains, and about escaping quotation marks in quoted parameters. Removed bits about parsing impossibilities.
• 2009-Apr-07 (nwaite) Added the Connection Handshake section; updated Client-State-ID and SS - Set State sections, among others, with handshake info.
• 2008-Sep-29 (nwaite) Enlarged Table of Contents and added some notes to a few directives.
• 2008-Jul-13 (nwaite) Started adding deduced meanings of the SS directive to the Client-State-ID table.
• 2008-Apr-21 (nwaite) Fleshed out various directives.
• 2008-Apr-20 (nwaite) Started and finished cleanup. Added examples where known. Fleshed out AT, JG, SB and SS directives.
• 2008-Apr-10 (nwaite) Retrieved original from http://www3.telus.net/kensit/NetAcquire/.

Suggestions for Improvement

• Add new directives for game events—such as a player joining a game or a player's cash changing—instead of using SV - Set Value directives.
• Create a new directive for game log messages (e.g. "Hey guys" sent as GM - Game Message, "> You drew tile 8C." sent as a new Game Log directive)