3. Game setup - HearthSim/kettle-design GitHub Wiki
Relations
-
QueuePlayer -> QueueStatus | Player -> MatchMaking
-
QueueCancel -> Ack | Player <-> MatchMaking
-
QueueTransition -> Ack | MatchMaking -> Player
-
CreateGame -> GameCreated | MatchMaking -> GameServer
-
JoinGame -> GameJoined | Player -> GameServer
-
GameFinished -> Ack | GameServer -> Management
Types
QueuePlayer
kettle:types/queue_player is used as request to the Matchmaking server. Until one player is matched with another,
that player is 'waiting in queue'.
-
Scenario: Instructs the server to use a generic set of rules for game setup. Possible values are explained by the enum GameScenario; and
-
AcountID: The identification of the account that will become a player; and
-
AccountName: Username of the player; and
-
HeroID: The card ID of the hero representing the player ingame; and
-
CardBack: The numeric representation of the cardback this player uses. See the xml file of all cardbacks for all possible values.
-
Cards: The card list contains the ID's of collectible cards.
- The card list is NOT A SET;
- There is an upper limit of 120 items;
- The list items are already shuffled, but the simulator SHOULD shuffle them again.
-
RulesOverride: Defines a specific start state for the player additive to the scenario preset:
- StartMana: The amount of mana the player has at the start of the game. The player will start his first turn with this amount of mana +1; and
- StartHandSize: The amount of cards in hand the player will have at the start of the game. this amount excludes the (possible) coin; and
- StartEntities: A list of entities that are under the control of this player at the start of the game.
{
"type": "kettle:types/queue_player",
"queue_player":
{
/*REQ*/ "scenario" := GameScenario:integer,
/*REQ*/ "accountID" := kettle:accounts/[account_id],
/*OPT*/ "account_name" := string,
/*REQ*/ "heroID" := kettle:cards/[card_id],
/*REQ*/ "card_back" := integer,
/*REQ*/ "cards":
[
kettle:cards/[card_id],
kettle:cards/[card_id],
..
],
/*OPT*/ "rules_override":
{
/*OPT*/ "start_mana" := integer, // Between 0 and 10
/*OPT*/ "start_hand_size" := integer, // Between 0 and 10
/*OPT*/ "start_entities":
[
kettle:types/entity,
kettle:types/entity,
..
]
}
}
}
QueueStatus
kettle:types/queue_status is used from Matchmaking server to Player. It's basically a keep-alive message
informing Player of his position in queue.
- Position: The position in the queue, a lower value means closer to the head. -1 can be provided as undefined value;
- QueueTime: The amount of seconds Player needs to wait before being matched to another player (on average).
{
"type": "kettle:types/queue_status",
"queue_status":
{
/*REQ*/ "position" := integer,
/*OPT*/ "queue_time" := integer,
}
}
QueueCancel
kettle:types/queue_cancel can be sent by Player as well as Matchmaking server.
The enumeration inside the object will inform of the reason.
- Reason: Argument for cancelling the queue. Possible values are explained by the enum Reason.
{
"type": "kettle:types/queue_cancel",
"queue_cancel":
{
/*OPT*/ "reason": Reason:integer,
}
}
QueueTransition
kettle:types/queue_transition is sent to Player. Player can go into 'playing game' state after receiving this object.
- GameID: The identification of the game to connect to;
- GamePassword: The password to use in order to connect to the game;
- ConnectionInfo: Object containing information about connecting to the game server.
- AccountID: The identification of the account of the player;
- IP: The IP address of the game server;
- Port: The port number to connect to.
{
"type": "kettle:types/queue_transition",
"queue_transition":
{
/*REQ*/ "gameID" := kettle:games/[game_id],
/*REQ*/ "game_password" := string,
/*REQ*/ "connection_info":
{
/*REQ*/ "accountID" := kettle:accounts/[account_id],
/*REQ*/ "ip" := string,
/*REQ*/ "port" := integer,
},
}
}
CreateGame
kettle:types/create_game is sent by Matchmaking server to make the Game server spin up a new simulator instance,
leading to the setup of a new game.
-
Scenario: Instructs the server to use a generic set of rules for game setup. Possible values are explained by the enum GameScenario; and
-
Password: The password for limiting access to the game. Only players who know the password can succesfully join the created game.
-
Players: Defines a list of player data, containing 1 or 2 entries. The player data consists of:
-
AcountID: The identification of the account that will become a player; and
-
AccountName: Username of the player; and
-
HeroID: String representation of the hero's card tag; and
-
CardBack: The numeric representation of the cardback this player uses. See the xml file of all cardbacks for all possible values.
-
Cards: The card list contains the tags (string representation) of collectible cards.
- The card list is NOT A SET;
- There is an upper limit of 120 items;
- The list items are already shuffled, but the simulator SHOULD shuffle them again.
-
RulesOverride: Defines a specific start state for the player additive to the scenario preset:
- StartMana: The amount of mana the player has at the start of the game. The player will start the first turn with this amount of mana +1; and
- StartHandSize: The amount of cards in hand the player will have at the start of the game. this amount excludes the (possible) coin; and
- StartEntities: A list of entities that are under the control of this player at the start of the game.
-
-
Reporting: Details to contact Management server, for sending game statistics:
- IP: The IP address of the Management server;
- Port: The port number to connect to.
{
"type": "kettle:types/create_game",
"create_game":
{
/*REQ*/ "scenario" := GameScenario:integer,
/*REQ*/ "password" := string,
/*REQ*/ "players":
[{
/*REQ*/ "accountID" := kettle:accounts/[account_id],
/*OPT*/ "account_name" := string,
/*REQ*/ "heroID" := kettle:cards/[card_id],
/*REQ*/ "card_back" := integer,
/*REQ*/ "cards":
[
kettle:cards/[card_id],
kettle:cards/[card_id],
..
],
/*OPT*/ "rules_override":
{
/*OPT*/ "start_mana" := integer, // Between 0 and 10
/*OPT*/ "start_hand_size" := integer, // Between 0 and 10
/*OPT*/ "start_entities":
[
kettle:types/entity,
kettle:types/entity,
..
]
}
}],
/*OPT*/ "reporting":
{
/*REQ*/ "ip" := string,
/*REQ*/ "port" := integer,
}
}
}
GameCreated
kettle:types/game_created is used as response to kettle:types/create_game indicating a new game was successfully started.
Players must use this information to handshake on their own with the Game server.
-
GameID: The identifier of the newly created game; and
-
ConnectionInfo: A list of connection details for all players. The length of this list is equal to the length of the list of player details within the
kettle:types/create_gamerequest object; and- AccountID: Account identification of the player;
- IP: IP address of the gameserver that the given player must connect to;
- Port: Port number of the gameserver that the given player must connect to.
-
GamePassword: Confirmation of the password given on
kettle:types/create_gamerequest object.
{
"type": "kettle:types/game_created",
"game_created":
{
/*REQ*/ "gameID" := kettle:games/[game_id],
/*REQ*/ "game_password" := string,
/*REQ*/ "connection_info":
[{
/*REQ*/ "accountID" := kettle:accounts/[account_id],
/*REQ*/ "ip" := string,
/*REQ*/ "port" := integer,
}],
}
}
JoinGame
kettle:types/join_game is used by players who want to connect to a game on a Game server.
The player must provide correct information to correctly authenticate himself to the gameserver. The gameserver will check all required values, before attaching the player to his game.
If the AccountIDproperty does not match with one of the competing Account's ID and the password is correct,
the player will join as spectator for the requested kettle:games/[game_id].
- AccountID: The identification of the account joining the game; and
- GameID: The ID of the game to join; and
- GamePassword: The password to enter the game.
{
"type": "kettle:/types/join_game",
"join_game":
{
/*REQ*/ "accountID" := kettle:accounts/[account_id]
/*REQ*/ "gameID" := kettle:games/[game_id]
/*REQ*/ "game_password" := string,
}
}
GameJoined
kettle:types/game_joined is used as response to kettle:types/join_game.
If the player succesfully received the kettle:types/game_joined object, it can send the request object kettle:types/get_game_state.
The gameserver will then respond with one or more kettle:types/history_block objects and 1 kettle:types/entity_choices object.
A spectatic player will not receive kettle:types/entity_choices, only kettle:types/history_block objects.
- Spectating: The value is true if the player joined the game as a spectator. Alternatively this value is false if the player joined his own game.
- Board: Indicates which board design is used for the game. Defaults to 10 TODO: Replace with enum of all possible boards
- MaxSecretsPerPlayer: Maximum amount of secrets a player is allowed to bring into play. Defaults to 5
- MaxFriendlyMinionsPerPlayer: Maximum amount of friendly minions a player can bring into play. Defaults to 7
{
"type": "kettle:/types/game_joined",
"game_joined":
{
/*REQ*/ "spectating" := bool,
/*REQ*/ "board" := integer,
/*REQ*/ "max_secrets_per_player" := integer,
/*REQ*/ "max_friendly_minions_per_player" := integer,
}
}
GameFinished
kettle:types/game_finished is sent by Game server to Management server.
- StartDateTime: Moment in time when the game was created. In UTC;
- EndDateTime: Moment in time when the game ended. In UTC;
- GameID: Identification of the game;
- Winners: List of Account identifiers that won the game;
- Losers: List of Account identifiers that lost the game;
- Result: Indicates the end state of the game. See enum GameResult for allowed values.
{
"type": "kettle:/types/game_finished",
"game_finished":
{
/*REQ*/ "start_datetime" := string,
/*REQ*/ "end_datetime" := string,
/*REQ*/ "gameID" := kettle:games/[game_id],
/*REQ*/ "winners":
[
kettle:accounts/[account_id],
kettle:accounts/[account_id],
..
],
/*REQ*/ "losers":
[
kettle:accounts/[account_id],
kettle:accounts/[account_id],
..
],
/*REQ*/ "result" := GameResult:integer,
}
}
Enums
GameScenario
GameScenario relates to a predefined ruleset that can be used to setup games.
-
The most significant byte (8bits) indicates the type of match (bitmask: 0xFF000000). This piece can be tested through direct bitmasking.
- PvP
- PvAI
-
The next 2 bytes (16bits) refer to a scenario stored at the simulator (bitmask: 0x00FFFF00). This piece must be compared integer-wise.
-
The last byte (8bits) indicates the format of the match (bitmask: 0x000000FF). This piece can be tested through direct bitmasking.
- Wild
- Standard
- Tavern brawl
The values are written in HEX format and the underlying type is int32.
0x0
Invalid value, this must not be used by any implementation!
0x01
Indicates Wild format.
0x02
Indicates Standard format.
0x04
Indicates Arena match.
0x08
Indicates Tavern brawl (WILD). Tavern brawls are always in the WILD format.
0x10 - 0x20 - 0x40 - 0x80
Reserved for NEW formats.
0x01XXXXXX
Match between 2 players. Information about 2 players must be given inside the containing object.
0x01000001
Wild format, match between 2 players.
0x01000002
Standard format, match between 2 players.
0x01000004
Tavern brawl, match between 2 players.
0x02XXXXXX
Match between 1 player and 1 simulator provided AI.
All forms of AI within the attached simulator are referred to as AI.
A simulator does not have to provide AI's, so it's allowed to respond with a kettle:types/NAck object.
Information about 1 player must be given inside the containing object.
If a match between 2 AI's is desired, 1 external AI must connect as Player .. or connect both external AI's as Players!
0x02000001
Wild format match, between 1 player and 1 idle AI. The idle AI only ends it's turn.
0x02000002
Standard format match, between 1 player and 1 idle AI. The idle AI only ends it's turn.
0x020001XX
Match between 1 player versus Easy Innkeeper AI.
0x020002XX
Match between 1 player, any mode, versus Hard Innkeeper AI.
0xXX0003XX - 0xXXFFFFXX
Scenario's can be uploaded to the simulator server and addressed by the returned ID.
GameResult
GameResult explains the end state of a game.
The values are written in HEX format and the underlying type is int32.
0x0
Invalid/Undefined.
0x1
GAME_DRAW. NO player won..
0x2
GAME_WON. 1, or more, players won..
0x3
GAME_CRASH. This practically results in a 'loss prevented' and still.. NO player won.