IPS Protocol Specification

This document describes the protocol that the Internet Pyraos Server uses for communicating with clients. Last update Sunday, 06-May-2001 17:10:26 CEST.


A tcp connection is used to transfer text messages between the server and all clients. Each message consists of one line of text, terminated by either LF (ascii code 10) or CR, LF (ascii codes 13, 10). The server uses only LF to terminate outgoing messages. The maximum message size is 200 characters, including the end of line character(s).

Most messages are composed by tokens that are separated by white space (at least one SPACE (ascii code 32) or TAB (ascii code 9) character), but in some messages, the last parameter may contain several words and consists of the last part of the message, including any white space.

Some information from the server is transferred in several messages (for example, who_reply). Such information blocks are terminated by the multiline_end message. The server guarantees that two multiline information blocks are never interleaved.

Since all messages consist of text only, the telnet program can be used to conenct to the server and experiment with messages. In fact, it is quite possible to play pyraos without using any additional client software. Hint: to play the game using telnet only, use the observe message to receive an ascii representation of the pyramid after each move.

Messages from the client to the server

Logging in and disconnecting

login name password
The client should respond to a login_request message from the server with this message.
Before closing the connection, the client should preferrably send this message to the server. This ensures that everyone connected to the server will receive a logout_notify message when the connection is dropped.

Setting up a match

match_offer opponent whostarts ruleset timelimit timeincrement
This message is sent to offer another player a game with the specified rules and time limits. If the opponent is logged in and is not playing a game already, a match_offered message will be sent to the opponent informing him of the offer. A user may offer a game to several other users without awaiting a reply. A match will be started with the first user to accept the offer (using the match_accept message); other outstanding offers are discarded.
match_accept opponent
See match_offer.
match_decline opponent
This message cancels an offer to play a game from another player.

Playing a game

move move
The possible locations of spheres in the pyramid are numbered as follows:

          0  1  2  3       16 17 18       25 26       29
          4  5  6  7       19 20 21       27 28
          8  9 10 11       22 23 24 
         12 13 14 15
Layer:     Bottom      Next-to-bottom  Next-to-top   Top
A move consists of a sphere to add to the pyramid, followed by zero to three spheres to remove from the pyramid. In the case when a sphere is lifted, one sphere is removed. More spheres may be removed if the added shpere makes a square (or line, if the lines ruleset is selected).

A sphere to be added to the pyramid is denoted by a + sign, followed by the position to place a sphere in the pyramid. A sphere to be removed from the pyramid is denoted by a - sign, followed by the position from where to remove a sphere in the pyramid. The move parameter may not contain spaces.

The special move pass can be used if and only if a player is out of spheres, and cannot lift a sphere or make a square (or line, if the lines ruleset is selected).

This message is used to end an ongoing game without declaring a winner. Both players have to issue the message to abort the game; no move may occur between the players' messages. When the first player sends the message, the opponent will be notified with a abort_requested message.
Transmitting this message during a game resigns the game, and the opponent is declared the winner.

Observing games

Produces a listing of the ongoing games on the server.
request_pyramid gameid
This message requests a snapshot of a game in play. The respone consists of a series of pyramid messages; see multiline_end.
observe gameid status
This message turns observation of a game on or off. If observation is turned on, the current playing position will be sent as a reply to this message, and after each move made in the game using the pyramid message.

Interacting with other users

Requests iformation about who is currently logged in from the server. The answer to this message is a series of who_reply messages.
listen channel
tell whom text


help topic
The server returns a series of help_reply messages as a response to this request.
The client should use this message to reply to the ping message from the server. The server disconnects upon failure of doing so in a reasonable time.

Messages from the server to the client

Logging in and disconnecting

This message is sent by the server just after the connection is established and informs the client that it needs to provide a user name using the login message.
login_accept name
login_deny reason
A login may be refused for several reasons: The user name supplied is too long or contains illegal characters, the user name is the name of a registered user and no password was supplied, the user name supplied is the name of a channel, the password is incorrect (for a registered user name), and probably more.

Starting and ending a match

match_accepted opponent
match_declined opponent
This message may be sent by the server to if the client has previously sent a match_offer message, offering the user opponent a game.
match_offered opponent whostarts ruleset timelimit timeincrement
match_start opponent whostarts ruleset timelimit timeincrement
match_end text
This message is sent to both players when a match is ended, whatever the reason.

Playing a game

move_ok move
Informs a player that the move he sent was successfully parsed and executed.
move_error reason
This message is sent to a client if the client sends a badly formatted or illegal move to the server.
moved move yourtime opponentstime
This message is sent by the server during a game if the opponent requested to abort the game with the abort message.

Observing games

listgames_reply gameno player1 vs. player2 rules timelimit timeincrement
matchstart_notify gameid Xplayer vs. Oplayer ruleset timelimit timeincrement
Each time a new match is started, the server sends this message to all users that are logged in.
matchend_notify gameid Xplayer vs. Oplayer reason
observe_ok gameid status
observe_error gameid
pyramid gameid next Xspheresleft Ospheresleft Xtimeleft Otimeleft lastmove Xname Oname ruleset timelimit timeincrement
This message actually consists of five lines. The first of these lines is as described above. The remaining four lines contain a textual representation of the current playing position.

Interacting with other users

tell_confirm whom
tell_error reason
told name whom message
listen_confirm channel status
listen_error channel reason
who_reply name description
This message is sent once for each user that is logged in to the server. See multiline_end.


info information
This message is used for general information from the server, for which it is not expected that clients respond automatically. This includes results of matches being played, etc.
error description
Some errors are reported by specialized error messages. This message is used by the server to report errors for which no such message exists.
Upon receival of this message, the client should promptly respond by a ping_reply message.
help_reply text
This message is sent once for each line of the help text. The end of the help text block is indicated by a multiline_end message.
login_notify name
This message is sent to all connected users when someone logs in to the server.
logout_notify name
This message is sent to all connected users when someone disconnects from the server.
This message specifies that a response from the server that uses several lines in ended. See who_reply, pyramid, help_reply, and listgames_reply.

Staffan Ulfberg