protocol

2 files changed, 38 insertions, 17 deletions

diff --git a/protocol.md b/protocol.md
new file mode 100644
index 00000000..7f86df7b
--- /dev/null
+++ b/protocol.md
@@ -0,0 +1,21 @@
+# undercooked protocol
+
+The protocol schema is defined in [`protocol.ts`](./test-client/protocol.ts)
+
+1. Connect to the server via TCP (on port 27031) or WebSocket (on port 27032)
+   and send/receive json on individual lines / text messages.
+2. Send the join packet with your username.
+3. Receive initial packets. The server will send the current game state.
+   - `joined` including your ID and Gamedata
+   - `update_map` for every tile
+   - `produce_item` for every item on a tile
+   - `add_player` for every player in the game
+4. Run the game loop
+   - Send your position every 40ms.
+   - Send `interact` when the player interacts with a tile. Make sure to set the
+     `edge` parameter consistently.
+   - Receive packets
+
+Collisions are handled by the clients. Whenever to players collide the player
+with the greater PlayerID is responsible for updating their own momentum and
+sending a packet to update that of the other player.
diff --git a/test-client/protocol.ts b/test-client/protocol.ts
index ccd891dd..d5605e37 100644
--- a/test-client/protocol.ts
+++ b/test-client/protocol.ts
@@ -1,29 +1,29 @@
-export type Vec2 = [number, number]
+export type Vec2 = [number, number] // x, y
 export type PlayerID = number
 export type ItemID = number
 export type ItemIndex = number
 export type TileIndex = number
 
 export interface Gamedata {
-    item_names: string[],
-    tile_names: string[],
+    item_names: string[], // Look-up table for ItemIndex
+    tile_names: string[], // Look-up table for TileIndex
 }
 
 export type PacketS =
-    { join: { name: string } }
-    | "leave"
-    | { position: { pos: Vec2, rot: number } }
-    | { interact: { pos: Vec2, edge: boolean } }
+    { join: { name: string } } // You join, sent as first packet.
+    | { position: { pos: Vec2, rot: number } } // Update your position
+    | { interact: { pos: Vec2, edge: boolean } } // Interact with some tile. edge is true when pressing and false when releasing interact button
+    | { collide: { player: PlayerID, force: Vec2 } } // Apply force to another player as a result of a collision
 
 export type PacketC =
-    { joined: { id: PlayerID, data: Gamedata } }
-    | { add_player: { id: PlayerID, name: string, hand?: [ItemID, ItemIndex] } }
-    | { remove_player: { id: PlayerID } }
-    | { position: { player: PlayerID, pos: Vec2, rot: number } }
-    | { take_item: { item: ItemID, player: PlayerID } }
-    | { put_item: { item: ItemID, pos: Vec2 } }
-    | { produce_item: { id: ItemID, pos: Vec2, kind: ItemIndex } }
-    | { consume_item: { id: ItemID, pos: Vec2 } }
-    | { set_active: { tile: Vec2, progress?: number } }
-    | { update_map: { pos: Vec2, tile: TileIndex } }
+    { joined: { id: PlayerID, data: Gamedata } } // You joined
+    | { add_player: { id: PlayerID, name: string, hand?: [ItemID, ItemIndex] } } // Somebody else joined (or was already in the game)
+    | { remove_player: { id: PlayerID } }  // Somebody left
+    | { position: { player: PlayerID, pos: Vec2, rot: number } } // Update the position of a players (your own position is included here)
+    | { take_item: { item: ItemID, player: PlayerID } }  // An item was taken from a tile
+    | { put_item: { item: ItemID, pos: Vec2 } } // An item was put on a tile
+    | { produce_item: { id: ItemID, pos: Vec2, kind: ItemIndex } } // A tile generated a new item
+    | { consume_item: { id: ItemID, pos: Vec2 } } // A tile removed an item
+    | { set_active: { tile: Vec2, progress?: number } } // A tile is doing something. progress goes from 0 to 1, then null when finished
+    | { update_map: { pos: Vec2, tile: TileIndex } } // A map tile was changed