API.md (5470B) [raw]
1 API Reference 2 ============= 3 4 Interaction with the server is 100% done through websockets at the following 5 endpoint: 6 7 ws://HOST:PORT/play 8 9 General Client Actions 10 ---------------------- 11 Each message from a client should have the "action" key with one of the 12 following values, along with additional info as needed. 13 14 For example, `ping` would be `{ "action": "ping" }`. 15 16 ### `ping` 17 18 Tells the server you're still alive (15s without any message will result in 19 being booted from the game). 20 21 Response will be `{ "msg_type": "pong" }`. 22 23 ### `join_table` 24 25 Joins a table to play (or spectate). First player to join creates the table 26 (with a password, if given). Additional players are required to provide that 27 password. 28 29 `table` + `player_name` must be a unique combo on the server. 30 31 Properties: 32 33 - `table`: Required, table name to join (i.e. "Party") 34 - `player_name`: Required, display name for table 35 - `password`: Optional, password for table 36 37 Gamestate will be broadcasted to all players on success. 38 39 ### `leave_table` 40 41 Remove player from table (standing up out of seat if necessary). 42 Hand is managed by game, so this is OK to call without destroying the 43 game state. 44 45 No response on success. 46 47 ### `list_tables` 48 49 WIP to enable a table discovery frontend. More info coming. 50 51 52 In-Game Actions 53 ---------------- 54 55 Same as before, requiring the "action" property. On success, all actions 56 [broadcast game state](#Server Responses) to all players (spectators and 57 seated players alike). 58 59 **NOTE:** All "Prerequisites" are handled by the server and need not be 60 checked by the client. An error message will be given to the client if a 61 prereq isn't met (ex: playing out of turn). This simplifies client creation 62 considerably. 63 64 ### `chat` 65 66 Sends chat message to all other Players at table. 67 68 Properties: 69 70 - `msg`: Required, message to send to other players 71 72 Responds with `{ "msg_type": "chat", "msg": "PLAYER: msg" }` to all players. 73 74 ### `take_seat` 75 76 Sits player at table. 77 78 Properties: 79 80 - `seat`: Required, 0-3 integer, open seat to occupy 81 82 ### `stand_up` 83 84 If seated, moves player to spectator view 85 86 ### `start_game` 87 88 Kicks off the first deal and starts the game. 89 90 Properties: 91 92 - `start_seat`: Optional, -1-3. -1 means random starting player, 0-3 93 means that seat should be the first dealer. 94 95 Prerequisites: 96 97 - Only valid during the `lobby` phase 98 - 4 players must be seated 99 100 ### `restart_game` 101 102 Creates a new Game entirely (resets table, scores, hands, etc). 103 104 Prerequisites: 105 106 - Only valid during the `end` phase 107 108 ### `order` 109 110 Orders dealer that `vote` suit should be trump (or passes). Server handles 111 validation of what suits can be nominated. 112 113 Properties: 114 115 - `vote`: either suit ('H', 'D', 'S', 'C') or 'pass' 116 - `loner`: 0 or 1 117 118 Prerequisites: 119 120 - Must be player's turn to act. 121 - Only valid during the `vote` phase 122 123 ### `play_card` 124 125 Plays card from player's hand. Server handles validation of whether the current 126 player truly has that card (and whether it is legal to play, i.e. following 127 suit). 128 129 Properties: 130 131 - `card`: two letter unique card. ex: 132 - 'NH' -- nine of hearts 133 - 'AS' -- ace of spades 134 - 'TD' -- ten of diamonds 135 136 Prerequisites: 137 138 - Must be player's turn to act. 139 - Only valid during the `play` phase 140 141 ### `dealer_swap` 142 143 Swaps dealer's card with the kitty card (like `play_card`, server validates 144 the card is in dealer's hand). 145 146 Properties: 147 148 - `card`: Same as `play_card` 149 150 Prerequisites: 151 152 - Must be the dealer 153 - Only valid during the `dealer_swap` phase 154 155 Server Responses 156 ---------------- 157 158 All server responses have the `msg_type` property, which the below sections 159 all represent. 160 161 ### `error` 162 163 As mentioned above, the server handles most of the coordination logic for the 164 clients (who's turn is it, do you have that card, etc). This prevents both 165 malicious clients, and makes it easier to create a new client. 166 167 In any case where an action was invalid for any reason, the server will 168 respond to the client with an error: 169 170 { "msg_type": "error", "errno": N, "msg": "Foo" } 171 172 "errno" is guaranteed to be unique and not change so that clients can 173 write custom error handling. See [Euchre::Errors](lib/Euchre/Errors.pm) for 174 the human readable constants. 175 176 ### `game_state` 177 178 This is the most common message from the server. It represents the game state, 179 and is sent on every successful action from any player to all other players at 180 the table (whether it's seat manipulation, cards played, etc) 181 182 The response looks like this: 183 184 ```json 185 { 186 "msg_type": "game_state", 187 "game" : { 188 "dealer": 0 189 "hand_lengths": [ 5, 5, 5, 5 ], 190 "out_player": -1, 191 "pass_count": 0, 192 "phase": "vote", 193 "players": [ "Alex", "Chris", "Jennie", "Lydecke" ], 194 "spectators": [ "Matt", "Sammy" ], 195 "tricks": [ 0, 0, 0, 0 ], 196 "trump": null, 197 "trump_nominee": "TS", 198 "turn": 1, 199 } 200 "hand": [ "TH", "JD", "KD", ... ], 201 "is_spectator": 0, 202 "table_id": "The Cool Kids Table", 203 } 204 ``` 205 206 Some general comments: 207 208 * `dealer`, `out_player`, and `turn` are seat numbers, 0 indexed (`out_player` is 209 the partner of a loner, -1 if no loners) 210 * `players` are the players names in order of seats 211 * `hand` is only present for players in the game 212 213 ### `chat` 214 215 Broadcasted to all players at table with the contents of a `chat` action. 216 217 Not logged on the server, only shown to clients that watch it. 218 219 ### `pong` 220 221 Response to `ping`. (Side note: I _know_ this isn't how one should properly 222 handle ping/pong frames, but this is an MVP here and my first foray into 223 websockets. It works!)