copy over comments

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,25 @@ 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,47 @@
 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, this corresponds with the previous x coordinate of the card in zones
+    // without y coordinate, in zones with a 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 version 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 joing 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 version of a type of 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;
 }