Sort pb cmake and add comments to proto files (#6163)

* sort cmake

* copy over comments

* clean up comments

common/pb/CMakeLists.txt

@@ -12,8 +12,8 @@ set(PROTO_FILES
     command_create_arrow.proto
     command_create_counter.proto
     command_create_token.proto
-    command_deck_del_dir.proto
     command_deck_del.proto
+    command_deck_del_dir.proto
     command_deck_download.proto
     command_deck_list.proto
     command_deck_new_dir.proto
@@ -34,10 +34,10 @@ set(PROTO_FILES
     command_next_turn.proto
     command_ready_start.proto
     command_replay_delete_match.proto
-    command_replay_list.proto
     command_replay_download.proto
-    command_replay_modify_match.proto
     command_replay_get_code.proto
+    command_replay_list.proto
+    command_replay_modify_match.proto
     command_replay_submit_code.proto
     command_reveal_cards.proto
     command_reverse_turn.proto
@@ -46,11 +46,11 @@ set(PROTO_FILES
     command_set_card_attr.proto
     command_set_card_counter.proto
     command_set_counter.proto
-    command_set_sideboard_plan.proto
     command_set_sideboard_lock.proto
+    command_set_sideboard_plan.proto
     command_shuffle.proto
-    commands.proto
     command_undo_draw.proto
+    commands.proto
     context_concede.proto
     context_connection_state_changed.proto
     context_deck_select.proto
@@ -78,6 +78,7 @@ set(PROTO_FILES
     event_game_joined.proto
     event_game_say.proto
     event_game_state_changed.proto
+    event_game_state_changed.proto
     event_join.proto
     event_join_room.proto
     event_kicked.proto
@@ -86,14 +87,15 @@ set(PROTO_FILES
     event_list_games.proto
     event_list_rooms.proto
     event_move_card.proto
+    event_notify_user.proto
     event_player_properties_changed.proto
     event_remove_from_list.proto
+    event_remove_messages.proto
     event_replay_added.proto
     event_reveal_cards.proto
     event_reverse_turn.proto
     event_roll_die.proto
     event_room_say.proto
-    event_remove_messages.proto
     event_server_complete_list.proto
     event_server_identification.proto
     event_server_message.proto
@@ -107,15 +109,15 @@ set(PROTO_FILES
     event_user_joined.proto
     event_user_left.proto
     event_user_message.proto
-    event_notify_user.proto
     game_commands.proto
+    game_event.proto
     game_event_container.proto
     game_event_context.proto
-    game_event.proto
     game_replay.proto
     isl_message.proto
     moderator_commands.proto
     move_card_to_zone.proto
+    response.proto
     response_activate.proto
     response_adjust_mod.proto
     response_ban_history.proto
@@ -124,6 +126,7 @@ set(PROTO_FILES
     response_deck_upload.proto
     response_dump_zone.proto
     response_forgotpasswordrequest.proto
+    response_get_admin_notes.proto
     response_get_games_of_user.proto
     response_get_user_info.proto
     response_join_room.proto
@@ -137,29 +140,27 @@ set(PROTO_FILES
     response_viewlog_history.proto
     response_warn_history.proto
     response_warn_list.proto
-    response_get_admin_notes.proto
-    response.proto
     room_commands.proto
     room_event.proto
+    server_message.proto
     serverinfo_arrow.proto
     serverinfo_ban.proto
-    serverinfo_cardcounter.proto
     serverinfo_card.proto
+    serverinfo_cardcounter.proto
     serverinfo_chat_message.proto
     serverinfo_counter.proto
     serverinfo_deckstorage.proto
     serverinfo_game.proto
     serverinfo_gametype.proto
+    serverinfo_player.proto
     serverinfo_playerping.proto
     serverinfo_playerproperties.proto
-    serverinfo_player.proto
     serverinfo_replay.proto
     serverinfo_replay_match.proto
     serverinfo_room.proto
     serverinfo_user.proto
     serverinfo_warning.proto
     serverinfo_zone.proto
-    server_message.proto
     session_commands.proto
     session_event.proto
 )

common/pb/color.proto

@@ -1,7 +1,16 @@
 syntax = "proto2";
+
+// Container for a 4 component color code
 message color {
+    // the red component of the color, limited to 256 values
     optional uint32 r = 1;
+
+    // the green component of the color, limited to 256 values
     optional uint32 g = 2;
+
+    // the blue component of the color, limited to 256 values
     optional uint32 b = 3;
+
+    // the opacity component of the color, limited to 256 values
     optional uint32 a = 4;
 }

common/pb/command_create_arrow.proto

@@ -2,15 +2,29 @@ syntax = "proto2";
 import "game_commands.proto";
 import "color.proto";
 
+// Command to draw an arrow from cards to either other cards or a player
 message Command_CreateArrow {
     extend GameCommand {
         optional Command_CreateArrow ext = 1011;
     }
+    // the player that has the card the arrow is drawn from
     optional sint32 start_player_id = 1 [default = -1];
+
+    // the zone that the card the arrow is drawn from is in
     optional string start_zone = 2;
+
+    // the id of the card that the arrow is drawn from
     optional sint32 start_card_id = 3 [default = -1];
+
+    // the player that has the card the arrow is drawn to, or that the arrow is drawn to if not a card
     optional sint32 target_player_id = 4 [default = -1];
+
+    // the zone that the card the arrow is drawn to is in, the player will be targeted if this is absent
     optional string target_zone = 5;
+
+    // the id of the card that the arrow is drawn to, the player will be targeted if this is absent
     optional sint32 target_card_id = 6 [default = -1];
+
+    // the color of the arrow
     optional color arrow_color = 7;
 }

common/pb/command_move_card.proto

@@ -1,26 +1,53 @@
 syntax = "proto2";
 import "game_commands.proto";
+
+// Container describing a single card to move
 message CardToMove {
+    // Id of the card in its current zone
     optional sint32 card_id = 1 [default = -1];
+
+    // Places the card face down, hiding its name
     optional bool face_down = 2;
+
+    // When moving add this value to the power/toughness field of the card
     optional string pt = 3;
+
+    // When moving sets the card to be tapped
     optional bool tapped = 4;
 }
 
+// Container of multiple cards to move
 message ListOfCardsToMove {
     repeated CardToMove card = 1;
 }
 
+// Command to move an amount of cards from one zone to another index/coordinate or another zone
 message Command_MoveCard {
     extend GameCommand {
         optional Command_MoveCard ext = 1027;
     }
+
+    // The player the zone the cards are in belongs to
     optional sint32 start_player_id = 1 [default = -1];
+
+    // The zone the cards start in
     optional string start_zone = 2;
+
+    // List of the cards and their new properties
     optional ListOfCardsToMove cards_to_move = 3;
+
+    // The player the zone the cards will be moved to belongs to
     optional sint32 target_player_id = 4 [default = -1];
+
+    // The zone the cards will be moved to
     optional string target_zone = 5;
+
+    // New x coordinate of the first card in the list
     optional sint32 x = 6 [default = -1];
+
+    // New y coordinate of the first card in the list
     optional sint32 y = 7 [default = -1];
+
+    // Inverts the x coordinate to apply from the end of the target zone instead of the start
     optional bool is_reversed = 8 [default = false];
 }

common/pb/event_game_state_changed.proto

@@ -2,13 +2,26 @@ syntax = "proto2";
 import "game_event.proto";
 import "serverinfo_player.proto";
 
+// Signals that the game state has changed.
+// If a field is present in this message, it will overwrite the client's game state.
+// Also used to provide the entire game state when joining a game.
 message Event_GameStateChanged {
     extend GameEvent {
         optional Event_GameStateChanged ext = 1005;
     }
+
+    // the list of players. Players contain their zones which contain all cards in the game
     repeated ServerInfo_Player player_list = 1;
+
+    // if the game has started
     optional bool game_started = 2;
+
+    // the player who is currently holding the turn
     optional sint32 active_player_id = 3;
+
+    // the current phase
     optional sint32 active_phase = 4;
+
+    // the amount of seconds since the game started
     optional uint32 seconds_elapsed = 5;
 }

common/pb/event_move_card.proto

@@ -1,20 +1,48 @@
 syntax = "proto2";
 import "game_event.proto";
 
+// Sent by the server to signal a single card was moved to update the client state
 message Event_MoveCard {
     extend GameEvent {
         optional Event_MoveCard ext = 2009;
     }
+
+    // The card id in the original zone
     optional sint32 card_id = 1 [default = -1];
+
+    // The name of the card in case it was not known yet
     optional string card_name = 2;
+
+    // The player whose zone the card started in
     optional sint32 start_player_id = 3 [default = -1];
+
+    // The original zone
     optional string start_zone = 4;
+
+    // The original position that the card was at.
+    // In zones without y coordinate, this corresponds with the previous x coordinate of the card.
+    // In zones with y coordinate, this value is not used.
     optional sint32 position = 5 [default = -1];
+
+    // The player who owns the new zone the card is in
     optional sint32 target_player_id = 6 [default = -1];
+
+    // The new zone the card is in
     optional string target_zone = 7;
+
+    // The new x coordinate (or new position for zones with no y coordinate)
     optional sint32 x = 8 [default = -1];
+
+    // The new y coordinate
     optional sint32 y = 9 [default = -1];
+
+    // The new id of the card if the card moved zone
     optional sint32 new_card_id = 10 [default = -1];
+
+    // If the card is face down, face down cards will not show their name
     optional bool face_down = 11;
+
+    // The provider id of the card in case it was not known yet.
+    // Extends the name to supply a specific printing of that type of card.
     optional string new_card_provider_id = 12;
 }

common/pb/game_commands.proto

@@ -1,4 +1,6 @@
 syntax = "proto2";
+
+// Commands that are sent during a game to change the game state
 message GameCommand {
     enum GameCommandType {
         KICK_FROM_GAME = 1000;
@@ -40,10 +42,15 @@ message GameCommand {
     extensions 100 to max;
 }
 
+// A wrapper around a normal game command that allows a privileged user to send a command on behalf of another player
 message Command_Judge {
     extend GameCommand {
         optional Command_Judge ext = 1033;
     }
+
+    // The player on whose behalf this command is sent
     optional sint32 target_id = 1 [default = -1];
+
+    // The wrapped game command
     repeated GameCommand game_command = 2;
 }

common/pb/game_event.proto

@@ -1,4 +1,6 @@
 syntax = "proto2";
+
+// Sent every time something happens in the game to update the client's state
 message GameEvent {
     enum GameEventType {
         JOIN = 1000;

common/pb/response.proto

@@ -1,4 +1,6 @@
 syntax = "proto2";
+
+// Sent immediately after a command with the same cmd_id, connecting it to the command sent to the server
 message Response {
     enum ResponseCode {
         RespNotConnected = -1;

common/pb/room_commands.proto

@@ -22,23 +22,52 @@ message Command_RoomSay {
     optional string message = 1;
 }
 
+// Create a new game in the room
 message Command_CreateGame {
     extend RoomCommand {
         optional Command_CreateGame ext = 1002;
     }
+
+    // game description shown in game list
     optional string description = 1;
+
+    // password users will have to provide to join the game
     optional string password = 2;
+
+    // amount of players needed to play
     optional uint32 max_players = 3;
+
+    // limits the game to only allowing users on the creator's buddy list to join
     optional bool only_buddies = 4;
+
+    // limits the game to only allowing registered users
     optional bool only_registered = 5;
+
+    // allows non players to view the game as spectator
     optional bool spectators_allowed = 6;
+
+    // allows spectators to join without password if false
     optional bool spectators_need_password = 7;
+
+    // allows spectators to use game say commands
     optional bool spectators_can_talk = 8;
+
+    // allows spectators to see hands and hidden information
     optional bool spectators_see_everything = 9;
+
+    // selection of game types as presented in the server's room configuration
     repeated uint32 game_type_ids = 10;
+
+    // the creator of the game will join it as a judge
     optional bool join_as_judge = 11;
+
+    // the creator of the game will join it as a spectator
     optional bool join_as_spectator = 12;
+
+    // set the starting life total
     optional uint32 starting_life_total = 13;
+
+    // share decklists with all players when selected
     optional bool share_decklists_on_load = 14;
 }
 

common/pb/serverinfo_card.proto

@@ -1,22 +1,56 @@
 syntax = "proto2";
 import "serverinfo_cardcounter.proto";
 
+// Container for all the properties of a single card
 message ServerInfo_Card {
+    // unique card id in this zone
     optional sint32 id = 1 [default = -1];
+
+    // name of this kind of card
     optional string name = 2;
+
+    // x coordinate in zone
     optional sint32 x = 3 [default = -1];
+
+    // y coordinate in zone
     optional sint32 y = 4 [default = -1];
+
+    // if the card is face_down, hiding its information
     optional bool face_down = 5;
+
+    // if the card is tapped, turned sideways
     optional bool tapped = 6;
+
+    // if the card is marked as attacking
     optional bool attacking = 7;
+
+    // the card's color
     optional string color = 8;
+
+    // the power/toughness field, displayed on the bottom right
     optional string pt = 9;
+
+    // an optional string placed over the card
     optional string annotation = 10;
+
+    // whether the card should be deleted when removed from the table, like a token
     optional bool destroy_on_zone_change = 11;
+
+    // whether the card should not be untapped when the untap command is sent
     optional bool doesnt_untap = 12;
+
+    // list of counters on the card
     repeated ServerInfo_CardCounter counter_list = 13;
+
+    // the player that owns the card this is attached to
     optional sint32 attach_player_id = 14 [default = -1];
+
+    // the zone of the card this is attached to
     optional string attach_zone = 15;
+
+    // the unique id of the card in that zone
     optional sint32 attach_card_id = 16 [default = -1];
+
+    // unique id of this kind of card, extends the name to specify a specific printing of a card
     optional string provider_id = 17;
 }

common/pb/serverinfo_game.proto

@@ -1,25 +1,65 @@
 syntax = "proto2";
 import "serverinfo_user.proto";
 
+// Container for information about a game in the room's game list
 message ServerInfo_Game {
+    // id of server the game is on
     optional sint32 server_id = 1 [default = -1];
+
+    // id of room the game is in
     optional sint32 room_id = 2 [default = -1];
+
+    // unique id of the game inside the room
     optional sint32 game_id = 3 [default = -1];
+
+    // user provided game description
     optional string description = 4;
+
+    // password required to join game
     optional bool with_password = 5;
+
+    // players required to play
     optional uint32 max_players = 6;
+
+    // mask of server defined game types
     repeated sint32 game_types = 7;
+
+    // user that created the game
     optional ServerInfo_User creator_info = 8;
+
+    // only buddies of the creator can join this game
     optional bool only_buddies = 9;
+
+    // only registered users can join this game
     optional bool only_registered = 10;
+
+    // if spectators are allowed to join
     optional bool spectators_allowed = 11;
+
+    // spectators need to enter the game
     optional bool spectators_need_password = 12;
+
+    // spectators can use cmdGameSay
     optional bool spectators_can_chat = 13;
+
+    // spectators receive private events for all players
     optional bool spectators_omniscient = 14;
+
+    // decklists are sent to all players when loaded
     optional bool share_decklists_on_load = 15;
+
+    // the current player count
     optional uint32 player_count = 30;
+
+    // the current spectator count
     optional uint32 spectators_count = 31;
+
+    // whether the game is currently ongoing
     optional bool started = 50;
+
+    // time that the game started at
     optional uint32 start_time = 51;
+
+    // whether the game is closed. Closed games are finished and can't be interacted with
     optional bool closed = 52;
 }