        ---------------------------------------------------------------
        htsprotocol specification 0.4.6
        ---------------------------------------------------------------


        CONTENTS
          1. Introduction
          2. Commands
            2.1. Command Syntax
            2.2. Explanations of all Commands
            2.3. List of Player-Commands
            2.4. List of Admin-commands
          3. Server-replies
            3.1. Format of Server-Replies
            3.2. Reply-Codes
              3.2.1. Type of Reply
              3.2.2. Reply-Code Groups
              3.2.3. Further distinction
          4. Server Commands
          5. Comments


        1. Introduction

        This document is the official specification of the Holsham
        Traders protocol, called 'htsprotocol', which is used for
        communication between the Holsham Traders client(s) and
        the server.

        Most of the time the Holsham Traders client(s) send commands
        to the server. Then it's up to the server to validate the
        request and then send a reply.

        Information which is important for other players, is sent to
        them by the server as server-commands.

        No client communicates with any other client directly. All
        traffic will be sent to the server, which will broadcast the
        necessary information to the respective clients.


        2. Commands


        2.1. Command Syntax

        All commands sent/received to/from the server/client(s) have
        the following syntax:

          command [argument1] [argument2] ... \n

        All commands have to end with a new line '\n'. This allows
        testing of the protocol implementation using telnet. In
        addition to that, when the receiving program does a recv() it
        will get all the data concatenated into one 'stream'. Using
        '\n' as a delimiter allows the receiver to divide the stream
        into single lines of commands again. If using fgets() the
        newline is also needed to mark the end of the line.

        Case is ignored in all commands, but not in the arguments of
        the commands.

        Arguments of commands are separated by spaces and if the
        arguments contain spaces, these arguments must be put in double
        quotation marks.


        2.2. Explanations of all Commands

        addplayer [playername] [password]

          Creates a new player called [playername]. The player's password is
          [password] and is specified as plain ASCII-text.

          Possible replies:
            500 Invalid playername.
            532 Player already exists.
            200 New player successfully created.

        delplayer [id|playername] [password]

          Deletes the player with the ID [id] (or the name [playername]) and
          the password [password].
          The player must be logged out. If you are logged in as admin, the
          player is deleted regardless of whether the password is correct
          or not.

          Possible replies:
            500 Syntax error.
            533 Player not found.
            537 The player to be deleted must be logged out.
            200 Player successfully deleted.
            501 Player deletion failed.

        login [playername] [password]

          Login as the player [playername] with the password [password].

          Possible replies:
            535 You are already logged in as "%s" (ID: %u).
            533 Player not found.
            535 "%s" (ID: %u) is already logged in.
            534 Wrong password.
            160 [SIZE OF DATA]
             |---> 260 [DATA]

        logout

          Logout from the game but still stay connected to the server.

          Possible replies:
            530 Not logged in.
            200 Logout successful.

        adminlogin [adminpassword]

          Gain admin permissions.

          Possible replies:
            536 You already have admin permissions.
            200 Admin permissions granted.
            534 Wrong password.

        adminlogout

          Drop admin permissions.

          Possible replies:
            531 You do not have admin permissions.
            200 Admin permissions dropped.

        save [name]

          Save the current game to 'name.sav'. Savegame support is not yet
          implemented!

          Possible replies:
            531 You do not have admin permissions.
            500 Savegame support is not yet implemented.
            501 Saving game failed.
            200 Successfully saved game.

        load [name]

          Load a previously saved game from 'name.sav'. Savegame support is
          not yet implemented!

          Possible replies:
            531 You do not have admin permissions.
            500 Savegame support is not yet implemented.
            501 Loading game failed.
            200 Successfully loaded game.

        passwd [id] [newpassword]

          Change the password of the player with the ID [id] to [newpassword].

          Possible replies:
            500 Syntax error.
            533 Player doesn't exist.
            200 Password successfully changed.
            530 Not logged in.
            531 You do not have admin permissions.

        version

          Get the htsserver-version.

          Possible replies:
            210 <version>

        protocol

          Get the version of htsprotocol which the server uses.

          Possible replies:
            210 <protocol-version>

        help

          Show a help message.

          Possible replies:
            210 <help message>

        quit

          Quit the game and disconnect from the server.

          Possible replies:
            221 Goodbye.

        chat [id|ALL] [message]

          Send a message to the player with the ID [id]. If 'ALL' is specified,
          the message is sent to all players.

          Possible replies:
            530 Not logged in.
            500 Syntax error.
            533 Player not found.
            520 Player not connected.

        transporter_drive [id] [destination]

          Drives the transporter with the ID [id] to the town with
          the ID [destination].

          Possible replies:
            500 Syntax error.
            530 Not logged in.
            551 Transporter doesn't exist.
            550 Destination town does not exist.
            556 Transporter is already in that town.
            160 [SIZE OF DATA]
             |---> 260 [DATA]

        transporter_set_name [id] [name]

          Set the name of the transporter with the ID [id] to [name].

          Possible replies:
            500 Syntax error.
            551 Transporter doesn't exist.
            200 Transporter name changed successfully.

        reconfig

          Reload the configuration options from the config-file. This
          does not overwrite any options given on the command-line.
          Additionally there are some options which cannot be changed
          via 'reconfig'. The server has to be restarted for them to
          be changed. This command is currently disabled as it is too buggy.

          Possible replies:
            531 You do not have admin permissions.
            500 The reconfig command doesn't work in this release.
            501 Re-reading configuration failed.
            200 Successfully re-read configuration.

        togglepause

          Pause/continue the game.

          Possible replies:
            531 You do not have admin permissions.
            200 Game is paused now.
            200 Game continues.

        shutdown

          Shutdown the server.

          Possible replies:
            531 You do not have admin permissions.
            200 Shutting down...

        buy_from_town_to_transporter [id] [what] [amount]

          Buy [amount] units of the good with the ID [what] from the town in
          which the transporter with the ID [id] is located.

          Possible replies:
            500 Syntax error.
            530 Not logged in.
            551 Transporter doesn't exist.
            550 Town doesn't exist.
            200 Buying successful.
            552 Good not available in town.
            553 Not enough goods in town.
            554 Transporter doesn't have enough free capacity.
            555 Transporter doesn't have enough money.

        sell_from_transporter_to_town [id] [what] [amount]

          Sell [amount] units of the good with the ID [what] from the
          transporter with the ID [id] to the town in which the transporter
          is located.

          Possible replies:
            500 Syntax error.
            530 Not logged in.
            551 Transporter doesn't exist.
            550 Town doesn't exist.
            200 Selling successful.
            552 Good not available in transporter.
            553 Not enough goods in transporter.
            554 Town doesn't have enough money.


        2.3. List of Player-Commands

        The following commands can be issued by normal players. No
        admin permissions are required.

        addplayer, delplayer, login, logout, adminlogin, passwd, version,
        protocol, help, quit, chat, transporter_drive, transporter_set_name,
        buy_from_town_to_transporter, sell_from_transporter_to_town.


        2.4. List of Admin-commands

        You need to have admin-permissions to be able to issue the
        following commands:

        delplayer, adminlogout, save, load, passwd, reconfig, togglepause,
        shutdown.


        3. Server-Replies
     
        Most of the time a client sends a command to the server, the
        server evaluates this command and then sends a reply to the
        client.

        Server replies to htsprotocol-commands should
          a) inform the client(s) about whether the last command
             succeeded or not, and why.
          b) ensure synchronization between the server and the client(s).
          c) let the client(s) know the state of the server.

        
        3.1. Format of Server-Replies

        A server-reply consists of a three digit number called reply-code,
        i.e. three alpha-numeric characters, followed by a space, followed
        by an explanatory text and a newline.

        Example:

        200 Logout successful.\n

        The text is meant to be read by humans, the number is intended
        to be used by the client software. The client software can
        either ignore the text or (better) display it to the user.
        The client software should not rely on the text, as it can
        change.

        Each client-command must produce a server-reply.


        3.2. Reply-Codes

        Reply-codes are three-digit numbers sent by the server in plain
        ASCII-text. Each of the three digits has a special meaning.


        3.2.1. Type of Reply

        The first digit of the reply-code determines the basic type of
        reply:

          0  <Unspecified as of yet>

          1  Positive Preliminary reply

             Requested action is initiated. Wait for further data. Do
             not send any new commands until that data arrives.

          2  Positive Completion reply

             Command successfully executed. New commands can be sent.

          3  Positive Intermediate reply

             Requested action is initiated. Server is waiting for
             further data.

          4  Transient Negative Completion reply

             Command accepted, but could not be executed. This is a
             temporary error. Try again. Replies belong in this group
             if the command can be repeated without any change on the
             client's side.

          5  Permanent Negative Completion reply

             Command not accepted and not executed. This is a permanent
             error. Do not try again with exactly the same command. You
             may have success with other arguments, for example.

          6  <Unspecified as of yet>

          7  <Unspecified as of yet>

          8  <Unspecified as of yet>

          9  <Unspecified as of yet>


        3.2.2. Reply-Code Groups

        The second digit of the reply-code determines the
        reply-code group:

          0  Syntax

             Syntax errors, too few or too many arguments for a
             command, obsolete or unknown commands, syntactically
             correct commands that don't fit in any group. Also bad
             sequence of commands or commands which exist but aren't
             allowed in a certain situation.

          1  Informational

             Replies to requests for information.

          2  Connections

             Successful connections, closed connections etc.

          3  Authentification / Accounting

             Login, logout, players, passwords, admin-permissions etc.

          4  Internal

             Memory errors, server too busy etc.

          5  Miscellaneous

             Misc. replies, ping-statistics.

          6  Game data and information

             Information which is used in the game directly. E.g. Town-names,
             amounts of goods etc. etc.

          7  <Unspecified as of yet>

          8  <Unspecified as of yet>

          9  <Unspecified as of yet>


        3.2.3. Further distinction

        The third digit of the reply-code is used to further
        differentiate between several replies. Use zero, if there is
        no need to differ between special replies.


        4. Server Commands

        htsprotocol implements several server-commands, i.e. commands
        sent by the server without any request from the client. These
        are used to inform the client about certain events which are
        important for the respective client, e.g. changes in the number
        of goods in a town, incoming messages from other players etc.

        Currently implemented server commands are:

        good_amount_update [town] [good] [amount]

          Inform the players who need this information, that the amount of
          the good with the ID [good] in the town with the ID [town] has
          changed to [amount].

        good_price_update [town] [good] [price]

          Inform the players who need this information, that the price of
          the good with the ID [good] in the town with the ID [town] has
          changed to [price].

        player_new [id] [playername]

          There is a new player with the ID [id] who is called [playername].

        player_remove [id]

          The player with the ID [id] has been removed.

        player_logged_in [id]

          The player with the ID [id] has logged in.

        player_logged_out [id]

          The player with the ID [id] has logged out.

        pause

          Indicates that the admin has paused the game.

        continue

          Indicates that the admin has continued a paused game.

        shutdown

          The server will be shut down now.

        login_timeout

          Your login-timeout has expired and you will be disconnected.

        chat [id] [message]

          The player with the ID [id] sent you the message [message].

        transporter_arrived [id] [player] [town]

          The transporter with the ID [id], which belongs to the player with
          the ID [player] has arrived in the town with the ID [town].

        transporter_left [id] [player] [town]

          The transporter with the ID [id], which belongs to the player with
          the ID [player] has left the town with the ID [town].


        5. Comments

        If you have any comments or suggestions, please write
        to Uwe Hermann <uh1763@hermann-uwe.de>.

