Skip to content

Commit 859c0dd

Browse files
MikeDev101MikeDev101
committed
Update docs
1 parent a0241f5 commit 859c0dd

File tree

1 file changed

+250
-20
lines changed

1 file changed

+250
-20
lines changed

‎delta.md‎

Lines changed: 250 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -25,17 +25,17 @@ All communication is considered "in-band" between peers. The packet schema is a
2525
"payload": { ... },
2626
"origin": "...",
2727
"target": "...",
28-
"ttl": 3,
28+
"ttl": 1,
2929
"id": "...",
3030
"method": "..."
3131
}
3232
```
3333

34-
* `opcode`: A string that defines the packet's purpose.
34+
* `opcode`: **(Required)** A string that defines the packet's purpose.
3535
* `payload`: Any arbitrary JSON-serializable data.
36-
* `origin`: **(Required if using a bridge)** The unique instance ID of the original peer that sent the message.
37-
* `target`: **(Required if using a bridge)** The unique instance ID of the final recipient. This can be a specific peer ID or a broadcast indicator (e.g., `*`).
38-
* `ttl`: **(Optional)** Time-To-Live. A number used for bridged/relayed messages. Each peer that forwards the message decrements this value. If `ttl` reaches 0, the packet is dropped.
36+
* `origin`: **(Required for bridge/relay/broadacasts)** The unique instance ID of the original peer that sent the message.
37+
* `target`: **(Required for bridge/relay/broadcasts)** The unique instance ID of the final recipient. This can be a specific peer ID or a broadcast indicator (e.g., `*`).
38+
* `ttl`: **(Required)** Time-To-Live. A number used for bridged/relayed messages. Each peer decrements this value before interpreting the packet. If `ttl` is below 0, the packet will be dropped. The default value is 1.
3939
* `id` & `method`: Optional properties for variable/list synchronization.
4040

4141
-----
@@ -47,40 +47,270 @@ These commands are sent directly between connected peers.
4747
| `opcode` | Description |
4848
| :--- | :--- |
4949
| **`NEGOTIATE`** | Sent by a client immediately after connecting to another peer. The `payload` contains an object with arbitrary key-value pairs detailing the client's capabilities (e.g., supported features, loaded plugins) for feature negotiation. |
50-
| **`HOST_LOBBY`** | Sent from a peer to its connections to announce it is the host of a lobby. The `payload` contains the lobby's state (name, password status, max players, etc.). |
51-
| **`REQUEST_JOIN`**| Sent from a new peer to any existing peer in a lobby to request entry. The receiving peer will forward this request to the current host. |
52-
| **`MANAGE_LOBBY`**| A dual-purpose command. Sent from the host to all peers to announce a change in the lobby's state (e.g., `{"method": "lock"}`). Also sent from a peer to the host to request an action (e.g., `{"method": "kick", ...}`). |
53-
| **`TRANSFER_HOST`** | Sent from the current host to another peer (`target`) to designate them as the new host. The recipient then sends a `HOST_LOBBY` broadcast. |
54-
| **`LOBBY_STATE`** | Sent by the host to a new peer in response to `REQUEST_JOIN`. The `payload` contains the complete current state of the lobby, granting entry. |
55-
| **`PEER_JOIN`** | Broadcast by the host to all peers when a new user has successfully joined. The `payload` is the new peer's user object. |
56-
| **`PEER_LEFT`** | Broadcast by the host when a peer disconnects. The `payload` contains the peer's ID. |
5750
| **`G_MSG`** | A Global Message. The sending peer sets `target` to `*` and sends it to its direct connections. Peers forward it based on the `ttl`. |
5851
| **`P_MSG`** | A Private Message. The `target` is a specific peer ID. Peers will attempt to bridge the message if not directly connected. |
5952
| `G_VAR`/`P_VAR` | Variable Sync message. Works like `G_MSG`/`P_MSG`. |
6053
| `G_LIST`/`P_LIST`| List Sync message. Works like `G_MSG`/`P_MSG`. |
6154
| `NEW_CHAN` | A control message sent to a `target` peer to negotiate a new, named data channel. |
55+
| `PING`/`PONG` | Control messages used for computing RTT. |
6256
| `HANGUP`/`DECLINE`| Voice call control signals sent to a specific `target` peer. |
57+
| `WARNING`/`VIOLATION`| State control messages. `WARNINGS` are safe and user-correctable. `VIOLATION`s will result in mandatory disconnects. |
58+
59+
#### Packet-specific syntax
60+
61+
##### **`NEGOTIATE`**
62+
**Negotiation is mandatory** for all variants of the Delta protocol.
63+
```js
64+
{
65+
"opcode": "NEGOTIATE",
66+
"payload": {
67+
"version": { // "version" is not intended for protocol versioning. It is purely for user-reference.
68+
"type": string, // Can be any value you want. Examples: Scratch, Go...
69+
"major": int,
70+
"minor": int,
71+
"patch": int,
72+
},
73+
"spec_version": 0, // Spec version is recommended for protocol versioning. Leave as 0.
74+
"plugins": [ // i.e. "chat", "sync", "discovery", ...
75+
string...
76+
],
77+
"is_bridge": bool,
78+
"is_relay": bool,
79+
"is_discovery": bool,
80+
}
81+
}
82+
```
83+
84+
##### **`PING`/`PONG`**
85+
Request messages start with `PING` and a `t1` value, containing a timestamp encoded as a numerical timestamp.
86+
87+
```js
88+
{
89+
"opcode": "PING",
90+
"payload": {
91+
t1: Date.now(),
92+
},
93+
"ttl": 1,
94+
}
95+
```
96+
97+
A reply message to `PING` should contain the original `t1` timestamp as well as a new numerical timestamp in `t2`.
98+
99+
```js
100+
{
101+
"opcode": "PONG",
102+
"payload": {
103+
t1: (PING payload).t1;
104+
t2: Date.now();
105+
},
106+
"ttl": 1,
107+
}
108+
```
63109

64110
-----
65111

66-
### Discovery Server Commands (Optional)
112+
### Discovery Server Commands
67113

68114
These commands are used to interact with an optional Discovery Server for matchmaking and peer resolution.
69115

70116
| `opcode` | Description |
71117
| :--- | :--- |
72-
| **`REGISTER_LOBBY`** | Sent by a host peer to the Discovery Server to make its lobby publicly listed. |
73-
| **`UNREGISTER_LOBBY`**| Sent by a host peer to remove its lobby listing from the Discovery Server. |
74-
| **`LIST_LOBBIES`** | Sent by any peer to request a list of all public lobbies. |
75-
| **`QUERY_PEER`** | Sent by any peer to resolve a `user@designation` address into a PeerJS connection ID. |
118+
| **`LOBBY_INFO`** | Requests specific details about a specified lobby ID. |
119+
| **`CONFIG_HOST`** | Creates a new lobby with a unique ID and settings. |
120+
| **`CONFIG_PEER`** | Joins a lobby with the specified ID and settings. |
121+
| **`LOBBY_LIST`** | Returns a list of all active, visible, password-free, and unlocked lobbies. |
122+
| `LOCK`/`UNLOCK` | Toggles the lock state of the lobby to prevent/allow new members from connecting. |
123+
| `SIZE`| Updates the maximum number of members allowed in the lobby. Set to -1 to allow unlimited members. |
124+
| `KICK` | Forcefully disconnects a member from the lobby. |
125+
| `HIDE`/`SHOW` | Toggles lobby visibility in the public lobby list, or through event broadcasts. |
126+
127+
#### Packet-specific syntax
128+
129+
##### **`CONFIG_HOST`**
130+
Requesting a lobby will use the following packet syntax:
131+
132+
```js
133+
{
134+
"opcode": "CONFIG_HOST",
135+
"payload": {
136+
"lobby_id": any, // must be serializable
137+
"password": string,
138+
"max_peers": int, // -1 or null = "unlimited", otherwise > 0
139+
"locked": bool,
140+
"hidden": bool,
141+
"metadata": any,
142+
},
143+
"ttl": 1,
144+
}
145+
```
146+
147+
If the specified ID exists:
148+
149+
```js
150+
{
151+
"opcode": "LOBBY_EXISTS",
152+
"ttl": 1,
153+
}
154+
```
155+
156+
A successful reply will return the following:
157+
158+
```js
159+
{
160+
"opcode": "CONFIG_HOST_ACK",
161+
"payload": any, // lobby_id
162+
"ttl": 1,
163+
}
164+
```
165+
166+
Upon creation (if not `hidden`), the following will be broadcasted:
167+
168+
```js
169+
{
170+
"opcode": "NEW_LOBBY",
171+
"payload": any, // lobby_id
172+
"ttl": 1,
173+
}
174+
```
175+
176+
##### **`CONFIG_PEER`**
177+
Joining a lobby will use the following packet syntax:
178+
179+
```js
180+
{
181+
"opcode": "CONFIG_PEER",
182+
"payload": {
183+
"lobby_id": any, // must be serializable
184+
"password": string,
185+
},
186+
"ttl": 1,
187+
}
188+
```
189+
190+
If the specified ID does not exist:
191+
192+
```js
193+
{
194+
"opcode": "LOBBY_NOTFOUND",
195+
"ttl": 1,
196+
}
197+
```
198+
199+
A successful reply will return the following:
200+
201+
```js
202+
{
203+
"opcode": "CONFIG_PEER_ACK",
204+
"payload": string, // lobby_id
205+
"ttl": 1,
206+
}
207+
```
208+
209+
All members of the lobby (including the host) will be
210+
sent the following:
211+
212+
```js
213+
{
214+
"opcode": "PEER_JOIN",
215+
"payload": string, // instance ID
216+
"ttl": 1,
217+
}
218+
```
219+
220+
Some lobbies may have a password set. If the lobby
221+
has one, three possible outcomes can occur.
222+
223+
If the lobby has a password and the value of `password`
224+
is empty:
225+
226+
```js
227+
{
228+
"opcode": "PASSWORD_REQUIRED",
229+
"ttl": 1,
230+
}
231+
```
232+
233+
If the `password` value is invalid:
234+
235+
```js
236+
{
237+
"opcode": "PASSWORD_FAIL",
238+
"ttl": 1,
239+
}
240+
```
241+
242+
A valid `password` will return this before `CONFIG_PEER_ACK`:
243+
244+
```js
245+
{
246+
"opcode": "PASSWORD_ACK",
247+
"ttl": 1,
248+
}
249+
```
250+
251+
##### **`LOBBY_LIST`**
252+
Requesting the list does not take any arguments.
253+
254+
```js
255+
{
256+
"opcode": "LOBBY_LIST",
257+
"ttl": 1,
258+
}
259+
```
260+
261+
The response will return a list of lobbies. This will also be sent to the client upon initial connection to the discovery server.
262+
263+
```js
264+
{
265+
"opcode": "LOBBY_LIST",
266+
"payload": [any...], // values will be serialized
267+
"ttl": 1,
268+
}
269+
```
270+
271+
##### **`LOBBY_INFO`**
272+
Requesting info requires a target.
273+
274+
```js
275+
{
276+
"opcode": "LOBBY_INFO",
277+
"payload": any, // target, must be serializable
278+
"ttl": 1,
279+
}
280+
```
281+
282+
The response will return an object.
283+
284+
```js
285+
{
286+
"opcode": "LOBBY_INFO",
287+
"payload": {
288+
"lobby_id": any,
289+
"host": string, // host instance ID
290+
"current_peers": int,
291+
"max_peers": int,
292+
"hidden": bool,
293+
"locked": bool,
294+
"metadata": any,
295+
}
296+
"ttl": 1,
297+
}
298+
```
76299

77300
-----
78301

79-
### Relay Server Commands (Optional)
302+
### Bridge Server Commands
80303

81304
These commands are used to bridge communication with clients on older CL2/3/4 protocols.
82305

83306
| `opcode` | Description |
84307
| :--- | :--- |
85-
| **`RELAY_MSG`** | Sent from a CL5.1 client to the Relay Server. The `payload` contains the original CL5.1 packet and a `legacy_target` field specifying the older client. The Relay translates and forwards the message. |
86-
| **`BRIDGE_MSG`** | Sent from the Relay Server to a CL5.1 client when a message arrives from a legacy client. The `payload` contains the translated message and information about the legacy sender. |
308+
| **`...`** | . . . |
309+
310+
### Relay Server Commands
311+
312+
These commands are used to improve the performance of broadcast messages.
313+
314+
| `opcode` | Description |
315+
| :--- | :--- |
316+
| **`...`** | . . . |

0 commit comments

Comments
 (0)