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, an Xid
  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.  
  string status = 6;                    // Resulting status of the match function
}

// 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. 
}

// Open Match's internal representation and wire protocol format for "Players".
// In order to enter matchmaking using the Frontend API, your client code should generate
// a consistent (same result for each client every time they launch) with an ID and 
// properties filled in (for more details about valid values for these fields,
// see the documentation). 
// Players contain a number of fields, but the gRPC calls that take a
// Player as input only require a few of them to be filled in.  Check the
// gRPC function in question for more details.
message Player{
  message Attribute{                
    string name = 1;                // Name should match a Filter.attribute field. 
    int64 value = 2;
  }
  string id = 1;                    // By convention, an Xid
  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.
  string assignment = 5;            // By convention, ip:port of a DGS to connect to 
  string status = 6;                // Arbitrary developer-chosen string. 
  string error = 7;                 // Arbitrary developer-chosen string.
}


// 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{
}

message Assignments{
    repeated Roster rosters = 1;
    string assignment = 10; 
}

// Messages for gRPC-served matchmaking functions.

// The message for passing in the per-request identifiers
// to a matchmaking function; used so it knows which records to
// write/update in state storage.
message Request {
    string profile_id = 1;
    string proposal_id = 2;
    string request_id = 3;
    string error_id = 4;
    string timestamp = 5;
}

// The message for passing all the necessary arguments to a 
// matchmaking function.
message Arguments{
    Request request = 1;
    MatchObject matchobject = 2;
}