1. Kettle Home - HearthSim/kettle-design GitHub Wiki

Kettle page on hearthsim.net

The Kettle Protocol

Kettle is a JSON-based protocol used to communicate game state and player inputs for Hearthstone. Both entities participating in the communication use the protocol in a request->response style. Kettle is modeled after the real Hearthstone protocol. However some communication content will not map exactly onto the Hearthstone protocol, because that would contribute to a non-intuitive context and cause confusion.

Communication participants

The Kettle protocol defines objects to be sent between any of the following participants in a communication:

  • Player (the client application)
  • Matchmaking server
  • Game server (simulator)
  • Management server: This participant could equal Player or a separate entity recording game results. Stove is an example of a management server, because it manages the database (and more).

Not all protocol objects are applicable to each communication between any of these participants. Each page on this wiki has a paragraph about which object is sent and/or received by which specific participant.

In the case of communicating with an actual Hearthstone client, an adapter program is needed to convert Kettle to the expected protocol.

Kettle IRI

This protocol definition uses International Resource Identification (IRI) strings to identify specific resources. For specific information about what each IRI means and what underlying type is used for transport, head to the Kettle IRI page.

Structure

1 Kettle PACKET consists of 1 header section and 1 data section. The data section contains exactly 1 Kettle Type OBJECT.

The Kettle packet is sent in 'Network Byte Order', meaning Big-endian. By default, TCP/IP implementations should convert primitives from 'Host Byte Order' to 'Network Byte Order' for you.

The content of all strings used as key is lower cased, using "snake_case" for content consisting of multiple words. This is also true for Type property values. The only exception on this rule is the full- and substring "ID", which is always expressed in UPPERCASE without prefixed underscore. The content of strings used as value are not restricted to any rules.

Header

Every Kettle packet begins with an unsigned int32 which encodes the version of the protocol AND size of the following data of the same packet. The version number is not allowed to change once the first Kettle packet has been transported. The server will respond with an error object if the Kettle version is not supported/not the latest definition.

  • The 28 most significant bits (bitmask: 0xFFFFFFF0) represent the size, in bytes, of the data inside the current packet. This permits 255 megabytes of data within one packet.

  • The 4 least significant, the remaining, bits (bitmask: 0x0000000F) will indicate the version number, where 0x1 indicates 'Alpha version'.

Data

The header is immediately followed by 1 UTF-8 encoded JSON-object aka Kettle Type object. The RFC section about JSON encoding states Unicode encoding must be used, to support internationalized strings. The data is effectively a string which encoding has a length equal to the size provided within the header of the packet.

Each object contains EXACTLY TWO properties:

  • A Type.

    • The keyname is litterally type!
    • It's value gives semantic meaning to the Payload property by using the string literal of the Types IRI. eg: "kettle:types/create_game"; and
  • A Payload.

    • The key name is derived from the value of the Type property, specifically the last component of the path. This name is not allowed to contain one of the reserved characters of IRI.
    • It's value is the actual packet data. The data could be a primitive value, a list of values or a JSON object. See Object Type index for more information.

Textual representation of a Kettle packet, containing exactly 1 Kettle Type object (CreateGame) :

0xFFFFFFF 0x1 
{
    // While in ALPHA the design is iterated a few times.
    // To prevent mismatching, the CreateGame object is not copied here as long as we're not stable!
}

Type object index (WIP)

The following Types are defined by the protocol:

Enum object index (WIP)

The following enumeration objects are used by declared Types:

Reference material

Understanding the HearthStone protocol

Link to Fireplace implementation of the protocol

Homestone's Fireplace communication snippet

Stove's Kettle communication snippet