Ossa Sepia

This is a request for public comment (questions, critique, discussion etc) on the current version of Eulora’s protocol for client-server communications that has been in works for a while now. Once this public discussion phase ends, the most significant aspects of this protocol will be effectively set in stone, since the procotol is central to any working client for Eulora. Consequently, your chance at having any significant input on it is *now* and only now. Any questions or feedback on it as well as any suggestions or requests related to it are most welcome, warmly appreciated and thoroughly considered *now*. By contrast, any whining and bitching over it at a later time will likely have at most some entertainment value – my entertainment that is. In fewer words: speak now or suffer later, your choice.

1. EuComms: Overall Goals:
1.1. All communications between clients and server to be encrypted.
1.2. Clients to be able to receive from server any data they lack (including maps, skins, sound or video content etcetera), on demand.
1.3. Clients to be able to choose and adjust both the level of security and their volume of communications with the server, as they will ultimately have to pay for the load that they generate.

2. EuComms relies on:
2.1. RSA with Keccak-based OAEP (via EuCrypt) for initial communication of OTPs (Serpent keys).
2.2. Serpent (via EuCrypt) for general communications.

3. Structure:
All communications between server and client will consist of packets up to 4096 bits in length, encrypted either via eucrypt.RSA or eucrypt.Serpent. The complete list of all such packets is included below.

Packets the client may send to the server:
3.1. Initial connection to server : client encrypts with the server’s public key and sends to the server a hello message; constructed as follows : following conversation in #trilema log, this hello message would actually end up multi-packet as it has to include the client’s public key (n,e so that’s currently 4096+2048 bits) instead of the id at 3.1.5 in the structure below:
3.1.1. Octet 0 – the length of the message in octets (43 or 76);
3.1.2. Octets 1 to 8 – the string “EuLoRa”;
3.1.3. Octets 9 to 10 – the major and minor versions of the communications protocol that the client wants to use;
3.1.4. Octets 11 to 42 – the client ID string, which will be equal to the eucrypt.keccak hash of the client binary. All client providers will be required to register all their ID strings with Minigame ; connections from clients with unknown ID strings will be rejected. Players will be notified of and helped to identify changes in their client software.
3.1.5. Octets 43 to 75 – the account ID string. If this field is omitted the server will create a new game account for the client.

3.2. Data (client sent)
3.2.1. Octet 0 – the length of the message in octets (multiple of 16 octets);
3.2.2. Octet 1 to 2 – descriptor of the type of data being sent (see annex A for datatypes);
3.2.3. Octet 3 to 5 – three octets ID of the item being sent;
3.2.4. Octet 6 to n – payload.

Packets the server may send to the client:
4.3. Data (server originated)
4.3.1. Octet 0 to 4 – the length of the message in octets (multiple of 16 octets, in principle limited to 65536 altogether and practically in the kbs anyway);
4.3.2. Octet 5 to 6 – descriptor of the type of data being sent (see annex A for datatypes);
4.3.3. Octet 7 to 10 – four octets ID of the item being sent;
4.3.4. Octet 11 to 16 – six octets counter of the chunk being sent (this limits downloadable items somewhat);
4.3.5. Octet 17 to n – payload.

Annex A — datatypes in client-server communication

NB: all data types below can in principle be sent by both client and server; however, data sent by the client is essentially a request to the server (i.e. it’s up to the server to decide whether it is valid and/or has any effect and/or what effect in game) while same data sent by the server is feedback/information (i.e. it reflects something that *has happened/exists already*).

In fewer words: client proposes, server disposes.

A.0 Basic types (used throughout the rest of sections in this Annex A)
A.0.0. char – character value on 1 octet
A.0.1. text – n*char where n will ALWAYS be specified clearly, right next to each and every text variable passed around
A.0.2. int8 – integer value on 1 octet
A.0.3. int16 – integer value on 2 octets
A.0.4. int32 – integer value on 4 octets
A.0.5. int64 – integer value on 8 octets
A.0.6. float – real value on 4 octets

A.1 Connection
A.1.1 Set of Serpent Keys

• int8 – number of keys in this set, n;
• n*(4*int64 + int32) octets – n Serpent keys (32 octets each + 4 octets ID for each, calculated as keccak hash of the 32 octets);
• int8 – 1 for server use, 2 for client use, anything else undefined currently.

A.1.2 Request Serpent Keys –> response is a “Set of Serpent Keys” (A.1.1)

• int8 – number of keys requested;
• int8 – value 1 for server use, 2 for client use, anything else undefined currently.

A.1.3 Choose Serpent Key

• int32 – ID of the key that will be used for communications from now on (depending on the key’s set, it’ll be used for server’s or client’s messages).

A.1.4 Burn & Choose Serpent Key

• int32 – ID of the key to remove from usable sets;
• int32 – ID of the key to use for future comms;

A.1.5 Unknown/Malformed Message received

• int64 – id of message that was not understood.

A.2 File Transfer
A.2.1 File Information

• int8 – length of file name in octets, n
• n*char – file name (string)
• int8 – file type
• int64 – octets per unit
• int64 – file size in unit given above
• int32 – file hash (keccak)

A.2.2 File Content

• int32 – file hash (keccak)
• int64 – octets per unit
• int64 – file size in unit given above
• unit*file_size*int8 – file content

A.2.3 Request File Information –> response is a “File Information” (A.2.1)

• int8 – length of file name in octets, n
• n*char – file name (string)

A.2.4 Request File Content –> response is a “File Content” (A.2.2)

• int8 – length of file name in octets, n
• n*char – file name (string)

A.2.5 Request File Information –> response is a “File Information” (A.2.1)

• int32 – file hash (keccak)

A.2.6 Request File Content –> response is a “File Content” (A.2.2)

• int32 – file hash (keccak)

A.3 Chat
A.3.1 Chat Public

• int64 – id of speaker
• int16 – length of string being said
• n*char – string being said

A.3.2 Chat Private

• int64 – id of target for this chat
• int64 – id of speaker
• int16 – length of string being said
• n*char – string being said

A.4 Character Actions & Activities
A.4.1 Basic action

• int64 – id of subject
• int64 – id of object
• int32 – id of action attempted (client-sent)/performed (server-sent) –> see Annex B for list of current basic actions

A.4.2 Item movement

• int64 – id of subject
• int64 – id of object
• int64 – quantity (stack count) to be moved
• int64 – id of destination object (i.e. own char’s id for “pickup”, container ID for move to container, sector id for “drop” or move from container to world, other char’s id for “trade” or “store” etc.)

A.4.3 Item movement with specified slot

• int64 – id of subject
• int64 – id of object
• int64 – quantity (stack count) to be moved
• int64 – id of destination object (i.e. own char’s id for “pickup”, container ID for move to container, sector id for “drop” or move from container to “world”, other char’s id for “trade” or “store” etc.)
• int64 – slot id

A.4.4 Activity –> this is meant to be sent by the server;

• int64 – id of activity
• int64 – duration (in seconds)
• int64 – start time (unix format)
• int8 – status: 0 -> finished/success; >0 -> ongoing / scheduled; <0 -> failed / aborted

A.4.5 Request Activity Information –> response is “Activity” above (A.4.4)

• int64 – id of requested activity

A.4.6 Train

• int64 – id of character
• int64 – id of skill to train

A.5 Environment & Graphics
NB: “requests” here are not actions of the character in the game as such but rather supporting raw API for the client; for instance, requests here include obtaining the id of own character or available maps.

A.5.1 List of Sectors

• int64 – number of sectors, n
• n*int64 – list with ids of available sector

A.5.2 Request list of sectors –> response will be “List of Sectors” above (A.5.1)

• int64 – character ID

A.5.3 Sector Map

• int64 – id of sector
• int8 – length of map filename (sector’s name)
• n*char – map filename (sector’s name)

A.5.4 Request sector map –> response will be “Sector Map” type above (A.5.3)

• int64 – id of sector

A.5.5 Item in sector (actor/character or object)

• int64 – id of item
• int64 – id of sector in which the item is located
• float – position of item: x coordinate
• float – position of item: y coordinate
• float – position of item: z coordinate
• int64 – id of graphics profile –> graphics profiles are so that the client can request and choose from alternative/equivalent actual files/meshes/icons/animations for this particular graphics profile
• int8 – length of name/label of item
• n*char – name/label of item

A.5.6 Request own char –> no payload here really since it’s accepted only from authenticated client so unambiguous anyway; response will be a “Item in sector” type above – it includes id of sector + id of char etc. (A.5.5)

A.5.7 Item in container

• int64 – id of item
• int64 – count
• int64 – parent item/actor id (i.e. inventory is simply actor-as-container)
• int64 – slot id
• int64 – id of graphics profile –> same story as at A.5.5 above
• int8 – length of name/label of item
• n*char – name/label of item

A.5.8 Request item –> response will be “Item in sector” or “Item in container” types above (A.5.6, A.5.7)

• int64 – id of item

A.5.9 Item Text Description (returned in response to a “view” basic action)

• int64 – id of item
• int64 – length of description
• n*char – text description

A.5.10 Item Text Content –> sent in response to “read” basic action

• int64 – id of item
• int64 – length of text content
• n*char – text content

A.5.11 Item List of Characteristics

• int64 – id of item
• int16 – number of characteristics
• n*int64- the ids of relevant characteristics for this item

A.5.12 Item Characteristic

• int64 – id of item
• int64 – id of characteristic
• int64(/float/int32/int16/char) – value of characteristic –> type here would depend on characteristic according to definition at A.5.13 below

A.5.13 Characteristic

• int64 – id of characteristic
• int8 – type of value of this characteristic (see A.0 above for the ids of data types that can appear here)
• int64 – length of name of characteristic, n
• n*char – name of characteristic
• int64 – length of name of category, c
• c*char – name of category

5.14 Request Characteristic –> response is “Characteristic” above (A.5.13)

• int64 – id of requested characteristic

A.5.15 Skill

• int64 – id of skill
• int64 – length of skill name
• n*char – skill name
• int64 – length of skill’s category name
• c*char – category name

A.5.16 Skill List

• int 64 – number of skills in this list
• n*int64- ids of skills in this list

A.5.17 Character’s Skill

• int64 – id of character
• int64 – id of skill
• int64 – current rank
• int64 – current knowledge points
• int64 – current practice points
• int64 – cost of knowledge to next rank
• int64 – cost of practice to next rank

A.5.18 Request Skill Information –> response will be Skill above (A.5.15)

• int64 – skill id

A.5.19 Request List of Skills –> response will be Skill List above (A.5.16)

• int64 – id of character whose skills are requested

A.5.20 Request Character’s Skill –> response will be Character’s Skill above (A.5.17)

• int64 – id of character whose current skill values are requested
• int64 – id of skill requested

A.5.21 Time of day (game time)

• int8 – hour
• int8 – minute

A.5.22 Request time of day (game time) –> no payload, response is Time of day above (A.5.21)

A.5.23 Movement Type

• int64 – id of this movement type
• int64 – id of graphic profile for this movement type
• float – x change
• float – y change
• float – z change
• float – x rotation
• float – y rotation
• float – z rotation
• int64 – length of name
• n*char – name of this movement type

A.5.24 Request movement type –> response will be “Movement Type” above (A.5.23)

• int64 – id of requested movement type

A.5.25 List of movement types

• int64 – number of available movement types
• n*int64- list of ids of available movement types

A.5.26 Request list of movements –> response will be a “List of movement types” above (A.5.25)

• int64 – id of item for which available movement types are requested

A.5.27 Set Movement Type

• int64 – id of item for which movement type is set
• int64 – id of movement type to set

A.5.28 Destroy Item

• int64 – id of item that is destroyed/vanishes

A.5.29 Set Item Position

• int64 – id of item
• int64 – id of sector in which the item is located
• int8 – position of item: x coordinate
• int8 – position of item: y coordinate
• int8 – position of item: z coordinate

A.5.30 Neutral message –> mainly for feedback e.g. “X killed himself”, “That tool is not useful anymore”, “You ranked up.”, “You got loot”

• int64 – length of text in characters, n
• n*int8 – text

A.5.31 Error message (in game)

• int64 – length of text in characters, n
• n*int8 – text

A.5.32 Success message (in game)

• int64 – length of text in characters, n
• n*int8 – text

A.5.33 Message of the day

• int64 – length of text in characters, n
• n*int8 – text

A.5.34 Request message of the day –> no payload here; answer will be “Message of the day” above (A.5.33)

A.5.35 Top

• int64 – duration in days from game’s “today” (i.e. 0 for today’s top, 30 for past months’ top etc.)
• int64 – length of text in characters, n
• n*int8 – text

A.5.36 Request Top –> answer will be “Top” above (A.5.35)

• int64 – duration in days from game’s “today” (i.e. 0 for today’s top, 30 for past months’ top etc.)

A.5.37 Graphics Profile

• int64 – id of this graphics profile
• float – width
• float – height
• float – depth
• int64 – number of contained slots with their own graphics profiles
• int8 – length of filename for icon
• m*int8 – icon filename
• int8 – length of filename for mesh
• n*int8 – mesh filename
• int8 – length of filename for texture
• p*int8 – texture filename
• int8 – length of filename for animation
• q*int8 – animation filename
• int8 – length of filename for sound
• r*int8 – sound filename

A.5.38 Request Top-Level Graphics Profile –> response is “Graphics Profile” above (A.5.37)

• int64 – id of requested graphics profile

A.5.39 Request Child Graphics Profile –> response is “Graphics Profile” above (A.5.37)

• int64 – length of path (i.e. how deep in the hierarchy is the graphics profile of interest)
• n*int64- ids forming the path to the desired graphics profile (e.g. 2,1,15 means the 15th slot of the 1st slot of top graphics profile number 2).

Annex B – List of currently available basic actions

B.1 Target –> this is less than View at B.2. below; character targets the object.

B.2 View –> this is a generic view and can be applied to anything (objects, actors, world included).

B.3 Read

B.4 Lock/unlock

B.5 Use/Combine/Sacrifice

B.6 Explore (current /explore, with target sector id)

B.7 Repair

B.8 Exchange –> this would be used for at least 3 currently distinct parts: trade, store, bank. As everywhere else, its exact effect depends on context.

B.9 Complete –> for actions that require explicit “accept” confirmation from player (e.g. trade)

B.10 Abort –> aborts what the character is doing (if the abort is possible, permitted and meaningful in the given context).

B.11 Attack –> for current “/die” simply use this with subject and object the same, namely own character.

Use the comment form below for any questions, comments, suggestions or desires you have regarding this communications protocol.