messages.proto

syntax = 'proto3';
package messages;
option go_package = "github.com/GoogleCloudPlatform/open-match/internal/pb";

// Open Match's internal representation and wire protocol format for "MatchObjects".
// In order to request a match using the Backend API, your backend code should generate
// a new MatchObject with an ID and properties filled in (for more details about valid
// values for these fields, see the documentation).  Open Match then sends the Match
// Object through to your matchmaking function, where you add players to 'rosters' and
// store any schemaless data you wish in the 'properties' field.  The MatchObject
// is then sent, populated, out through the Backend API to your backend code.
// 
// MatchObjects contain a number of fields, but many gRPC calls that take a
// MatchObject as input only require a few of them to be filled in.  Check the
// gRPC function in question for more details.
message MatchObject{
  string id = 1;                        // By convention, a UUID
  string properties = 2;                // By convention, a JSON-encoded string
  string error = 3;                     // Last error encountered. 
  repeated Roster rosters = 4;          // Rosters of players.  
  repeated PlayerPool pools = 5;        // 'Hard' filters, and the players who match them.  
}

// Data structure to hold a list of players in a match.  
message Roster{
    string name = 1;                 // Arbitrary developer-chosen, human-readable string. By convention, set to team name. 
    repeated Player players = 2;     // Player profiles on this roster.
}

// A 'hard' filter to apply to the player pool.
message Filter{
    string name = 1;                // Arbitrary developer-chosen, human-readable name of this filter. Appears in logs and metrics. 
    string attribute = 2;           // Name of the player attribute this filter operates on.
    int64 maxv = 3;                 // Maximum value.  Defaults to positive infinity (any value above minv).
    int64 minv = 4;                 // Minimum value.  Defaults to 0.  
    Stats stats = 5;                // Statistics for the last time the filter was applied. 
}

// Holds statistics
message Stats{
    int64 count = 1;                // Number of results.
    double elapsed = 2;             // How long it took to get the results. 
}

// PlayerPools are defined by a set of 'hard' filters, and can be filled in
// with the players that match those filters.
//
// PlayerPools contain a number of fields, but many gRPC calls that take a
// PlayerPool as input only require a few of them to be filled in.  Check the
// gRPC function in question for more details.
message PlayerPool{
    string name = 1;                // Arbitrary developer-chosen, human-readable string.
    repeated Filter filters = 2;    // Filters are logical AND-ed (a player must match every filter).
    Roster roster = 3;              // Roster of players that match all filters.
    Stats stats = 4;                // Statisticss for the last time this Pool was retrieved from state storage. 
}

// Data structure to hold details about a player
message Player{
  message Attribute{                
    string name = 1;                // Name should match a Filter.attribute field. 
    int64 value = 2;
  }
  string id = 1;                    // By convention, a UUID 
  string properties = 2;            // By convention, a JSON-encoded string
  string pool = 3;                  // Optionally used to specify the PlayerPool in which to find a player. 
  repeated Attribute attributes= 4; // Attributes of this player.
}


// Simple message to return success/failure and error status.
message Result{
    bool success = 1;
    string error = 2;
}

// IlInput is an empty message reserved for future use.
message IlInput{
}

// Simple message used to pass the connection string for the DGS to the player. 
// DEPRECATED: Likely to be integrated into another protobuf message in a future version. 
message ConnectionInfo{
    string connection_string = 1;   // Passed by the matchmaker to game clients without modification. 
}

message Assignments{
    repeated Roster rosters = 1;
    ConnectionInfo connection_info = 2;
}