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.

General

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

name: The user name by which the player will be known on the server. The name should contain no spaces.
password: This parameter is optional and is required for registered user names only.

The client should respond to a login_request message from the server with this message.

hangup

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

opponent: Selects the user that is offered a game.
whostarts: Specifies who is to move first. Valid values are me, opponent, and random.
ruleset: Selects the rules to be used in the game. Valid values are nolines, lines, and noremove
timelimit: Specifies the maximum time allowed for one player in seconds. A value of 0 offers an untimed game.
timeincrement: Specifies a time in seconds to be added to the maximum allowed time for each move made. The parameter has to be provided also when timelimit is 0.

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

opponent: The user name of the player whose game offer is accepted.

See match_offer.

match_decline opponent

opponent: The user name of the player whose game offer is declined.

This message cancels an offer to play a game from another player.

Playing a game

move move

move: The move to make; see description below.

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).

abort

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.

resign

Transmitting this message during a game resigns the game, and the opponent is declared the winner.

Observing games

listgames

Produces a listing of the ongoing games on the server.

request_pyramid gameid

gameid: The id of the game for which the current position is requested, as given by listgames_reply. If omitted, the position of game the user that issues the message is currently playing is returned.

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

gameid: The id of the game to observe, as given by listgames_reply.
status: on or off.

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

who

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

channel:

tell whom text

whom: The name of another user, or the name of a channel.
text: The message to be sent to the user or channel. The parameter may contain spaces and is terminated by the end of line character.

Miscellaneous

help topic

topic: An optional specification of the help subject.

The server returns a series of help_reply messages as a response to this request.

ping_reply

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

login_request

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

name: The user name supplied with the login message from the client.

login_deny reason

reason: The reason that the login failed. This parameter may contain several words and is terminated by the end of line character.

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

opponent: The user name of the opponent that accepted a match offer.

match_declined opponent

opponent: The name of the user that declined a match offer.

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

opponent: The name of the user that offers a game.
whostarts: The player to move first, either opponent, you, or random.
ruleset: See match_offer.
timelimit: See match_offer.
timeincrement: See match_offer.

match_start opponent whostarts ruleset timelimit timeincrement

opponent: The user name of the opponent.
whostarts: See match_offered.
ruleset: See match_offer.
timelimit: See match_offer.
timeincrement: See match_offer.

match_end text

text: Text describing the outcome of the game. This parameter may contain spaces and is terminated by the end of line character.

This message is sent to both players when a match is ended, whatever the reason.

Playing a game

move_ok move

move: The move made. See move.

Informs a player that the move he sent was successfully parsed and executed.

move_error reason

reason: A text describing the reason of failure.

This message is sent to a client if the client sends a badly formatted or illegal move to the server.

moved move yourtime opponentstime

move: The opponent's last move. See move.
yourtime: The maximum time for the client receiving this message to make a move.
opponentstime: The time that the opponent will have to make the next move.

abort_requested

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

gameno:
player1:
player2:
rules:
timelimit:
timeincrement:

matchstart_notify gameid Xplayer vs. Oplayer ruleset timelimit timeincrement

gameid: The id of the game that is started.
Xplayer: The user name of the first player to move.
Oplayer: The user name of the other player.
ruleset: See match_offer.
timelimit: See match_offer.
timeincrement: See match_offer.

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

gameid: The id of the game that ended.
Xplayer: The user name of the first player to move.
Oplayer: The user name of the other player.
reason: The reason that the game ended (such that one of the players won, resigned, or that the game was aborted); this parameter may contain spaces and is terminated by the end of line character.

observe_ok gameid status

gameid: The id of the game for which the observe status is changed. See listgames_reply.
status: The observe status of game gameid ofter the change; this parameter takes the value on or off.

observe_error gameid

gameid: The id of the game (see listgames_reply) for which a change of observation status was requested.

pyramid gameid next Xspheresleft Ospheresleft Xtimeleft Otimeleft lastmove Xname Oname ruleset timelimit timeincrement

gameid: The id of this game, as given by listgames_reply.
next: The next player to move: X or O.
Xspheresleft: The number of spheres that player 1 has left.
Ospheresleft: The number of spheres that player 2 has left.
Xtimeleft: The time in seconds left for player 1.
Otimeleft: The time in seconds left for player 2.
lastmove: The last move of this game; see move. If a move has not yet occurred in the game, this parameter will be na.
Xname: The user name of the first player.
Oname: The user name of the other player.
ruleset: See match_offer.
timelimit: See match_offer.
timeincrement: See match_offer.

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

whom: The user name or channel name corresponding to a tell message.

tell_error reason

reason: A textual description of the reason that the tell command failed.

told name whom message

name: The originator of a message, that is, the user that issued the tell message.
whom: The name of the user (i.e., you), or the name of the channel to which the message was directed.
message: The text told by the originator of the message.

listen_confirm channel status

channel:
status:

listen_error channel reason

channel:
reason:

who_reply name description

name: The user name of a user that is logged in to IPS.
description:

This message is sent once for each user that is logged in to the server. See multiline_end.

Miscellaneous

info information

information: General information from the server. This parameter may contain spaces and is terminated by the end of line character.

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

description: A textual description of the error that occurred. This parameter may contain spaces and is terminated by the end of line character.

Some errors are reported by specialized error messages. This message is used by the server to report errors for which no such message exists.

ping

Upon receival of this message, the client should promptly respond by a ping_reply message.

help_reply text

text: General help, or help on a selected topic. See help.

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

name: The user name of the user that logged in to IPS.

This message is sent to all connected users when someone logs in to the server.

logout_notify name

name: The user name of the user that left the server.

This message is sent to all connected users when someone disconnects from the server.

multiline_end

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