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 `STR`s.
- `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](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](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)