furnace/papers/multiplayer.md

multiplayer protocol

this is a concept! it has not been implemented yet!

the Furnace protocol is described here.

information

all numbers are little-endian.

the following fields may be found in "size":

• f indicates a floating point number.
• STR is a UTF-8 zero-terminated string.
• CFG is the same as STR, but contains a config.
• ??? is an array of variable size.
• S?? is an array of STRs.
• 1?? is an array of bytes.
• 2?? is an array of shorts.
• 4?? is an array of ints.

two player IDs are reserved:

• 0: system
• 1: host (console)

two usernames are reserved:

• SYSTEM
• HOST

some characters are not allowed in usernames: 0x00-0x1f, @, 0x7f-0x9f, 0xd800-0xdfff, 0xfeff, 0xfffe and 0xffff.

header

size | description
-----|------------------------------------
  3  | "fur" header
  1  | packet type
  4  | sequence number

the sequence number always starts at 0.

client to server packets (init)

0x00: keep-alive

this packet keeps a connection alive. the server shall respond with a packet of type 0x00 (keep-alive). if the client does not receive any packets during 30 seconds, it will disconnect from the server. likewise, if the server does not receive any packets during 30 seconds, it will disconnect the client.

0x01: start connection

size | description
-----|------------------------------------
  1  | reason
     | - 0: information
     | - 1: join
  3  | padding
  4  | client version
 STR | host name (may be blank)

after sending, you will receive a packet of type 0x01 (information), 0x02 (disconnect) or 0x03 (authenticate).

0x02: disconnect

size | description
-----|------------------------------------
 STR | reason

0x03: auth response

size | description
-----|------------------------------------
  1  | type
     | - 0: open
     | - 1: password
     | - 2: token
 --- | **open response**
 STR | username
 --- | **password response**
  1  | password type
     | - 0: plain text
     | - 1: SHA-512
 STR | account name
 ??? | password
 --- | **token response**
 STR | token

server to client packets (init)

0x00: keep-alive

this packet keeps a connection alive. it is a response to a client's keep-alive packet.

0x01: information

size | description
-----|------------------------------------
  4  | server version
  2  | online players
     | - if it is 65535, this information is concealed.
  2  | maximum players
     | - 0 means unlimited.
 STR | server version (string)
 STR | server name
 STR | server description
 STR | project name

the client may send a 0x00 (keep-alive) packet after receiving this one within 5 seconds. connection is then closed.

0x02: disconnect

size | description
-----|------------------------------------
 STR | reason

after being sent, the connection is closed.

0x03: authenticate

size | description
-----|------------------------------------
  1  | authentication type
     | - 0: open
     | - 1: password
     | - 2: token

0x04: authentication success

size | description
-----|------------------------------------
  4  | player ID
 STR | username
 CFG | properties

client to server packets (session)

0x10: request project

the client may only send this once every minute.

0x11: participate

size | description
-----|------------------------------------
  1  | status
     | - 0: spectate
     | - 1: join

0x12: send chat message

size | description
-----|------------------------------------
 STR | message

0x13: send command

size | description
-----|------------------------------------
 STR | command
  2  | number of arguments
 S?? | arguments

0x14: get player list

no other information required.

0x15: project submission request

no other information required

0x16: project submission information

size | description
-----|------------------------------------
  4  | project size
 32  | SHA-256 sum of project
 STR | project name

this is followed by several 0x17 (project data) packets representing a Furnace song. see format.md for more information.

0x17: project submission data

size | description
-----|------------------------------------
  4  | offset
  4  | length
 ??? | data...

the client will send a packet with project size as offset and 0 as length to indicate end of data. the server subsequently loads the project.

server to client packets (session)

0x10: project information

size | description
-----|------------------------------------
  4  | project size
 32  | SHA-256 sum of project
 STR | project name

this is followed by several 0x13 (project data) packets representing a Furnace song. see format.md for more information.

0x11: project data

size | description
-----|------------------------------------
  4  | offset
  4  | length
 ??? | data...

the server will send a packet with project size as offset and 0 as length to indicate end of data. the client subsequently loads the project.

0x12: participate status

size | description
-----|------------------------------------
  1  | status
     | - 0: denied
     | - 1: allowed

0x13: message

size | description
-----|------------------------------------
  4  | player ID
  8  | time (seconds)
  4  | time (nanoseconds)
  4  | message ID
  1  | type
     | - 0: chat, public
     | - 1: chat, private
     | - 2: notification, info
     | - 3: notification, warning
     | - 4: notification, urgent
 STR | message

0x14: system message

size | description
-----|------------------------------------
 STR | message

0x15: chat message edited

size | description
-----|------------------------------------
  4  | message ID
 STR | message
     | - an empty message means deleted.

0x16: player list

size | description
-----|------------------------------------
  2  | number of players
 --- | **player entry** (×players)
  4  | ID
  2  | latency (ms)
  1  | participating?
     | - 0: no
     | - 1: yes
  1  | status
     | - 0: normal
     | - 1: away
     | - 2: busy
 STR | name
 STR | IP address
     | - if empty, then server is not disclosing IP addresses.

this is sent after receiving 0x14 (get player list).

0x17: project submission request status

size | description
-----|------------------------------------
  1  | status
     | - 0: denied
     | - 1: allowed

this is sent after a project submission request is accepted. if the status is 1, the client shall submit a project.

0x18: project submission complete

size | description
-----|------------------------------------
  1  | status
     | - 0: error
     | - 1: success
 STR | additional information

0x19: player joined

size | description
-----|------------------------------------
  4  | ID
 STR | name

0x1a: player left

size | description
-----|------------------------------------
  4  | ID

client to server packets (project)

0x20: request orders

0x21: request instrument

0x22: request wavetable

0x23: request sample

0x24: request patterns

0x25: request sub-song

0x26: request song info

0x27: request asset list

0x28: request patchbay

0x29: request grooves

0x30: alter orders

size | description
-----|------------------------------------
  4  | transaction ID

0x31: alter instrument

0x32: alter wavetable

0x33: alter sample

0x34: alter pattern

0x35: alter sub-song

0x36: alter song info

0x37: alter asset list

0x38: alter patchbay

0x39: alter grooves

0x3a: alter chips

0x3b: alter chip settings

server to client packets (project)

0x20: orders

0x21: instrument

0x22: wavetable

0x23: sample

0x24: pattern

0x25: sub-song

0x26: song info

0x27: asset list

0x28: patchbay

0x29: grooves

0x30: transaction response

size | description
-----|------------------------------------
  1  | status
     | - 0: error
     | - 1: success
     | - 2: success but request again
 STR | additional information

client to server packets (interact)

0x40: engine command

0x41: playback

server to client packets (interact)

0x40: engine command

0x41: playback

client to server packets (extension)

server to client packets (extension)