6. Player Simulator interaction - HearthSim/kettle-design GitHub Wiki

Relations

EntityChoices -> ChooseEntities | GameServer -> Player
OptionsBlock -> ChooseOption | GameServer -> Player
OptionsBlock -> Concede | GameServer -> Player
ChooseOption -> HistoryBlock | Player -> GameServer
ChooseOption -> NAckOption | Player -> GameServer

EntityChoices :- enum ChoiceType
OptionsBlock :- Options/Pass
OptionsBlock :- Options/EndTurn
OptionsBlock :- Options/Power
Options/Power :- SubOption

Types

EntityChoices

kettle:types/entity_choices objects are sent from the GameServer to the Player. This object represents a choice the player has to make about the given list of entities. The player makes a choice by selecting certain entities from the presented entity list.

ChoiceID: Unique identifier of the choice set; 1-indexed
ChoiceType: Indicates in what context the choice was made; Possible values are explained by the enum ChoiceType;
Source: The entity ID that caused a choice to be made;
PlayerID: The ID of the player;
HideChosen: If True, the chosen entities will be hidden from sight;
CountMin: The minimum amount of entities to choose; For mulligan, this is 0
CountMax: The maximum amount of entities to choose; For mulligan, this is 3 or 4 (depending on which player goes first)
Entities: The list of entity ID's to choose from.

{
    "type": "kettle:types/entity_choices",
    "entity_choices": 
    {
        /*REQ*/ "choiceID" := kettle:games/[game_id]/choices/[choice_id],
        /*REQ*/ "choice_type" := ChoiceType:int32,
        /*OPT*/ "source" := kettle:games/[game_id]/entities/[entity_id],
        /*REQ*/ "playerID" := kettle:games/[game_id]/players/[player_id],
        /*REQ*/ "hide_chosen" := boolean,
        /*REQ*/ "count_min" := integer,
        /*REQ*/ "count_max" := integer,
        /*REQ*/ "entities" = 
                [
                    kettle:games/[game_id]/entities/[entity_id],
                    kettle:games/[game_id]/entities/[entity_id],
                    ..                    
                ],
    }
}

ChooseEntities

kettle:types/choose_entities is a response object, sent by Player to GameServer, to the kettle:types/entity_choices object.

This object contains all chosen entities, while the ChoiceID property value equals the value of the same property in the kettle:types/entity_choices object.

ChoiceID: Unique identifier of the choice set this object responds to; 1-indexed
ChoiceType: Validation of the type of choice;
Entities: The list of chosen entity ID's.

{
    "type": "kettle:types/entity_choices",
    "entity_choices": 
    {
        /*REQ*/ "choiceID" := kettle:games/[game_id]/choices/[choice_id],
        /*REQ*/ "choice_type" := ChoiceType:int32,
        /*REQ*/ "entities" = 
                [
                    kettle:games/[game_id]/entities/[entity_id], 
                    kettle:games/[game_id]/entities/[entity_id],  
                    ..
                ],
    }
}

OptionsBlock

kettle:types/options_block objects are sent from the GameServer to Player. This object holds all possible option objects the Player can perform as next move. The Player can select exactly one option!

Valid option objects are all types contained by the IRI path types/options/:

kettle:types/options/pass
kettle:types/options/end_turn
kettle:types/options/power

OptionsID: Unique identifier of this options set; 1-indexed
Options: List of possible actions Player can perform.

{
    "type": "kettle:types/options_block",
    "options_block": 
    {
        /*REQ*/ "optionsID" := kettle:games/[game_id]/options/[option_id],
        /*REQ*/ "options" :=
                [
                    kettle:types/options/..,
                    kettle:types/options/..,
                    ..
                ],
    }
}

Options/Pass

kettle:types/options/pass objects give Player the option to Pass. This means Player is out of other options. => Green end-turn button.

OptionIndex: Value keeping track of the position of this option object. 1-indexed

{
    "type": "kettle:types/options/pass",
    "pass": 
    {
        /*REQ*/ "option_index" := integer,
    }
}

Options/EndTurn

kettle:types/options/end_turn objects give Player the option to 'end the turn'. Other options are available as well. => Yellow end-turn button.

OptionIndex: Value keeping track of the position of this option object. 1-indexed

{
    "type": "kettle:types/options/end_turn",
    "end_turn": 
    {
        /*REQ*/ "option_index" := integer,
    }
}

Options/Power

kettle:types/options/power objects contain instructions about possible play actions.

OptionIndex: Value keeping track of the position of this option object; 1-indexed
MainOption: The first/main action to perform, this is practically bringing an entity into play;
SubOptions: Followup actions, like 'Choose One', to perform after MainOption property is done.

{
    "type": "kettle:types/options/power",
    "power": 
    {
        /*REQ*/ "option_index" := integer,
        /*OPT*/ "main_option" := kettle:types/sub_option,
        /*OPT*/ "sub_options" =
                [
                    kettle:types/sub_option,
                    kettle:types/sub_option,
                    ..
                ]
    }
}

SubOption

kettle:types/sub_option objects represent a single action or a followup action.

If followup, this is the 'Choose one' effect. For this effect, the next set or entities to choose from are known (not random). Each target represents a (card) entity to pick from (only 1).

SubOptionIndex: Value keeping track of the position of this suboption object; 1-indexed
EntityID: The identifier of the Entity linked to this option. This entity triggers an effect;
Targets: EntityID's which will be affected by the effect of the dereferenced EntityID property.

{
    "type": "kettle:types/sub_option",
    "sub_option": 
    {
        /*REQ*/ "sub_option_index" := integer,
        /*REQ*/ "entityID" := kettle:games/[game_id]/entities/[entity_id],
        /*REQ*/ "targets" =
                [
                    kettle:games/[game_id]/entities/[entity_id],
                    kettle:games/[game_id]/entities/[entity_id], 
                    ..
                ]
    }
}

ChooseOption

kettle:types/choose_option is the response object from Player to a received sequence of kettle:types/options_block objects.

OptionID: The same ID as the option object sequence this object responds to; 1-indexed
Target: The EntityID of the target this option will have an effect on. Use -1 as 'no target selected';
OptionIndex: Index of the chosen option; 1-indexed
SubOptionIndex: Index of chosen SubOption. Use -1 if no suboptions were provided; 1-indexed
Position: Position on the board where a minion is player. Defaults to position 0. 0-indexed

{
    "type": "kettle:types/choose_option",
    "choose_option": 
    {
        /*REQ*/ "optionID" := kettle:games/[game_id]/options/[option_id],
        /*REQ*/ "option_index" := integer,
        /*OPT*/ "target" := kettle:games/[game_id]/entities/[entity_id],
        /*OPT*/ "sub_option_index" := integer,
        /*OPT*/ "position" := integer, // Typically between 1 and 7
    }
}

NAckOption

kettle:types/nack_option is an object sent from the simulator to the player rejecting the one option that the player sent to the simulator. The client must resync it's state with the gameserver, kettle:types/get_game_state must be used.

OptionID: The same ID as the option object sequence this object responds to;

{
    "type": "kettle:types/nack_option",
    "nack_option": 
    {
        /*REQ*/ "optionID" := kettle:games/[game_id]/options/[option_id]
    }
}

Concede

kettle:types/concede is the object sent by Player to inform the GameServer of the intent to resign the game.

{
    "type": "kettle:types/concede",
    "concede":
    {
        // Empty object
    }
}

Enums

ChoiceType

ChoiceType Represents the the semantic value of the EntityChoices object.

The values are written in HEX format and the underlying type is int32.

0x0

Invalid.

0x1

Mulligan. This indicates that Player is chosing cards to replace with new cards from the deck zone.

!~ Mismatch with the actual HS protocol; The client sends the cards to keep, instead of 'to swap', to the server

0x2

General.

OptionType

Unused, each enumvalue has it's own kettle type.

Optiontype represents the semantic value of an option object.

The values are written in HEX format and the underlying type is int32.

0x1

Pass. => kettle:types/options/pass

0x2

End turn. => kettle:types/options/end_turn

0x3

Power. This means playing something. => kettle:types/options/power

Other sources

Understanding the HearthStone protocol

Homestone's Fireplace communication snippet

Stove's Kettle communication snippet