The Obby protocol consists of commands sent between a client and a server. There is one command per line, possibly with a colon and some parameters. Note that integral parameters are sent in hexadecimal representation. Newline characters, colon characters and backspace characters are escaped to \n, \d or \b respectively.
For a tutorial-like walkthrough of a basic Obby 0.3 session, see AnnotatedObbySession. (This may be helpful if you wish to add Obby support to another editor or interact with Obby in other ways.)
When a client connects to a server, the server sends:
The obby_welcome command specifies what protocol version the server uses. The net6_encryption means that the server wants an encrypted connection. The "0" parameter means that the server requests encryption; the client would use "1".
The client responds:
The server sends:
At this point, the client starts a TLS handshake. After that, the connection is encrypted.
The client logs in:
The parameters are the username, the user's colour, the global password, and the user's password. The two latter can be empty or omitted, when applicable.
If login and authentication are successful, the server continues:
obby_sync_init:1 net6_client_join:b:username:1:1:ff0000 obby_sync_final
The obby_sync_init command tells the client how many net6_client_join commands to expect. The fields of net6_client_join are net6 user ID, username, encryption flag (in this context, always true), Obby user ID, and Obby colour.
There is a difference between a net6 user and a obby user. A net6 user is a client that has connected to the server and performed a login. Each net6 user has a unique ID (11 in the example above, or hexadecimal b). A obby user is a user participating at an obby session and has also a unique ID (1). The difference is that the obby user is not discarded when the client exits. When he rejoins with the same name he is recognized as an already existing user and is assigned the ID that user had before. obby users are also serialized when storing an obby session.
A client needs to subscribe to a document to get its content and subsequent changes. Document IDs consist out of the obby ID of the user who created the document and a ID which is unique in relation to all other documents created by the user (usually a counter). Thus a subscribtion request for the first document of the first user looks like this:
The server then sends the current version of the document in chunks (a continuous string belonging to one author, whose ID is given as the last part of the packet):
obby_document:1 1:sync_init obby_document:1 1:sync_chunk:text:1
After all chunks are sent, the client's subscription is broadcast to all other clients:
The protocol is subject to changes between major release series.