The dopewars network protocol

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 thetes for sound effects, although pretty much any event in the game that you can think of can conceivably have a sound (e.g. when players join or leave the game). These sounds should be in WAV format, and should probably be no more than a second or two in length. Later versions of dopewars may also be able to play longer repeating sounds (i.e. music) if you're interested in contributing this. Use the SourceForge Data forum to see what sounds other people are working on.

  • Suggestions for future improvements are always welcomed at the SourceForge Open Discussion forum. These can be anything from "the game interface is confusing" through "more game locations are needed" to "what about a hospital". (I can't guarantee that such suggestions will ever make it into dopewars, but it's a lot easier if I know they exist! Also, it's far more likely to happen if you write the code - see the tips for developers page.)

  • Bug reports are always useful. Register them with the SourceForge bug tracker. If I don't know the problem exists, I can't fix it... The more information you can give here, the better. In particular, I need to know your operating system - e.g. Linux or Windows. For Linux, gdb stack traces of the core file are most useful.

  • Configuration files can be included in future distributions. If you run a customised game, and think others might want to play with your configuration, or at least use it as an example, then post it to the SourceForge Data forum...

  • Translation of dopewars into your language will enable you to play the game in your native tongue, and will also help others that speak the same language. It's pretty easy, too - all you have to do is edit a simple text file! See the i18n pages.

    • Last update: 22-07-2002
    Valid XHTML 1.1

    ./usr/share/doc/dopewars/html/developer.html0000644000000000000000000000353110142751220021270 0ustar rootroot00000000000000 Notes for developers

    Notes for developers

    You are free to make whatever changes to the code you wish, as long as you abide by the terms set out in the GNU General Public License. Obviously, I only have a limited amount of time to devote to dopewars development, and so encourage discussion of the dopewars code, documentation and concept, and particularly welcome suggested improvements.

    You are free to distribute modified versions of the code, again subject to the licence, but I also welcome patches to the code at my email address, benwebb@users.sf.net. If I choose to include these patches in a new dopewars version, you will of course be credited in the changelog (unless, of course, you don't want to be).

    If you wish to write your own client to connect to a dopewars server, then you need to understand the protocol that dopewars uses, which is documented here.

    The definitive source on the internal workings of the dopewars game code is the source code itself. It is not exactly "self-documenting", but I have endeavoured to add sufficient documentation to the source where necessary; any discussion here of the internal workings, however, may be incomplete, out of date, and possibly misleading. Feel free to email me at the address above with questions on this; I might possibly even know the answers!

    Last update: 15-07-2002
    Valid XHTML 1.1

    ./usr/share/doc/dopewars/html/metaserver.html0000644000000000000000000001531010142751220021456 0ustar rootroot00000000000000 The dopewars metaserver

    The dopewars metaserver

    Every dopewars server is different, due to their differing locations and configurations. Thus some centralised system for listing the currently available servers and displaying some sort of comment about the games running on them is necessary, to enable client players to pick the game that most suits them. This is the function of the dopewars metaserver.

    Metaserver location

    The metaserver is a PHP script which lives at SourceForge. It is accessed by both dopewars servers and clients via TCP connection to port 80, by standard HTTP.

    The "old" metaserver

    Versions of dopewars prior to 1.5.1 used a different metaserver system, which is now deprecated. Although the old system will continue to run for some time, it will eventually be discontinued, so it is recommended that dopewars servers and clients are upgraded to the latest version.

    Using the metaserver from the client

    Players who want to use the metaserver to list the currently available servers should go to this link, or just follow the "Active servers" link from the main dopewars web page. It cannot be guaranteed that all the listed servers are functional - they may, for example, have been registered in error, or a server may have crashed since being added to the list - but the list is checked daily for service, and so there is at least a good chance that the servers listed there will be working.

    The metaserver, being an ordinary web page, should work happily on most machines which have web access. A problem occurs, however, if your connection to the Web is via an enforced proxy server (i.e. traffic on port 80 from your machine is blocked by firewall). dopewars can be configured to connect via a proxy server without too much difficulty; if your proxy server is at proxy.com on port 8080 then you should add the following lines to your dopewars configuration file:-
    MetaServer.ProxyName="proxy.com"
    MetaServer.ProxyPort=8080

    Using the metaserver from the server

    People running servers who do not want their details listed by the metaserver should disable the metaserver comunication of the server with the MetaServer.Active=0 configuration file setting, or the -S command line option. Servers which do register their details can have their accompanying comment set with the MetaServer.Comment configuration file setting.

    Each dopewars server notifies the metaserver of its current status, and sends this data on startup and shutdown, and when players leave or join the game. See the server page for more details.

    The server, just like the client, may have trouble connecting to the metaserver if you are using a web proxy; see the information above for fixing this problem.

    But it's displaying the wrong name!

    Once connected to the metaserver, you may find that it displays the IP address of your server and not its domain name, or that it gets the domain name wrong. This is usually because your DNS is not set up to translate your IP into a domain name, or because you have multiple domain names for the one IP, and can be remedied by specifying the hostname with the MetaServer.LocalName variable in your dopewars configuration file. For security reasons, the metaserver will only accept this given name if it in turn maps to your IP address.

    On other occasions, the metaserver will mistakenly display the name of your web proxy. In this case, you will need to override the hostname that the metaserver guesses for your machine with one you choose yourself. This is again done by specifying the hostname with the MetaServer.LocalName variable. In order to prevent abuse of this facility, you must obtain a password from the metaserver maintainer to authenticate your chosen hostname. Email the maintainer, giving the exact hostname you want to use (be aware that this is case-sensitive) and you will be given a password. Specify this password with the MetaServer.Password variable in the dopewars configuration file.

    For example, if you wish your server to be known as dope-serv.com and you have emailed the maintainer, receiving the password Dope-Auth, then add the following to the dopewars configuration file:-
    MetaServer.LocalName="dope-serv.com"
    MetaServer.Password="Dope-Auth"

    Restart your dopewars server, or send it a SIGUSR1 signal, for changes to these variables to take effect.

    But my server has a dynamic IP...

    Finally, your server's IP may be resolved happily, but you may have a connection to the internet which assigns you a dynamic IP. Consider what happens if your connection is broken before the dopewars server exits; the metaserver will list the IP of the "old" server, and you will now have no way of removing that entry when your connection comes back up, as your IP will be different. In this case, you can email the metaserver maintainer, and specify a blank MetaServer.LocalName variable. You will again receive a MetaServer.Password variable (see above), which the metaserver will use to identify "your" server; now, when your internet connection is restored, the server registration with the "new" IP will automatically replace the "old" one.

    Last update: 15-07-2002
    Valid XHTML 1.1

    ./usr/share/doc/dopewars/html/protocol.html0000644000000000000000000006263410142751220021155 0ustar rootroot00000000000000 The dopewars network protocol

    The dopewars network protocol

    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 thetes for sound effects, although pretty much any event in the game that you can think of can conceivably have a sound (e.g. when players join or leave the game). These sounds should be in WAV format, and should probably be no more than a second or two in length. Later versions of dopewars may also be able to play longer repeating sounds (i.e. music) if you're interested in contributing this. Use the SourceForge Data forum to see what sounds other people are working on.

  • Suggestions for future improvements are always welcomed at the SourceForge Open Discussion forum. These can be anything from "the game interface is confusing" through "more game locations are needed" to "what about a hospital". (I can't guarantee that such suggestions will ever make it into dopewars, but it's a lot easier if I know they exist! Also, it's far more likely to happen if you write the code - see the tips for developers page.)

  • Bug reports are always useful. Register them with the SourceForge bug tracker. If I don't know the problem exists, I can't fix it... The more information you can give here, the better. In particular, I need to know your operating system - e.g. Linux or Windows. For Linux, gdb stack traces of the core file are most useful.

  • Configuration files can be included in future distributions. If you run a customised game, and think others might want to play with your configuration, or at least use it as an example, then post it to the SourceForge Data forum...

  • Translation of dopewars into your language will enable you to play the game in your native tongue, and will also help others that speak the same language. It's pretty easy, too - all you have to do is edit a simple text file! See the i18n pages.

    • Last update: 22-07-2002
    Valid XHTML 1.1

    ./usr/share/doc/dopewars/html/developer.html0000644000000000000000000000353110142751220021270 0ustar rootroot00000000000000 Notes for developers

    Notes for developers

    You are free to make whatever changes to the code you wish, as long as you abide by the terms set out in the GNU General Public License. Obviously, I only have a limited amount of time to devote to dopewars development, and so encourage discussion of the dopewars code, documentation and concept, and particularly welcome suggested improvements.

    You are free to distribute modified versions of the code, again subject to the licence, but I also welcome patches to the code at my email address, benwebb@users.sf.net. If I choose to include these patches in a new dopewars version, you will of course be credited in the changelog (unless, of course, you don't want to be).

    If you wish to write your own client to connect to a dopewars server, then you need to understand the protocol that dopewars uses, which is documented here.

    The definitive source on the internal workings of the dopewars game code is the source code itself. It is not exactly "self-documenting", but I have endeavoured to add sufficient documentation to the source where necessary; any discussion here of the internal workings, however, may be incomplete, out of date, and possibly misleading. Feel free to email me at the address above with questions on this; I might possibly even know the answers!

    Last update: 15-07-2002
    Valid XHTML 1.1

    ./usr/share/doc/dopewars/html/metaserver.html0000644000000000000000000001531010142751220021456 0ustar rootroot00000000000000 The dopewars metaserver

    The dopewars metaserver

    Every dopewars server is different, due to their differing locations and configurations. Thus some centralised system for listing the currently available servers and displaying some sort of comment about the games running on them is necessary, to enable client players to pick the game that most suits them. This is the function of the dopewars metaserver.