2. Kettle IRI - HearthSim/kettle-design GitHub Wiki

Kettle page on hearthsim.net

The Kettle IRI

An IRI is the international equivalent to URI, which is used to IDENTIFY things. URI's cannot identify 2 things at the same time, there must be a 1-on-1 mapping in the URI->thing direction!

These identifiers must not be seen as a dictionary key, but rather as a flat value. It's not the purpose of URI to point to the LOCATION of things, that's URL.

The Kettle IRI is defined as:

scheme:path

The scheme is always the string kettle.

The path can be split up into components by exploding on the forward slash character, /. All components of the IRI are lowercased, using snake_case if multiple words per component are needed.

Usage

Each IRI definition describes it's own underlying type and practical value. If an IRI is used within the protocol definition, it's practical value is assumed with respect to the underlying type!

The use of square brackets inside the IRI indicate a placeholder of a semantically appropriate value that's contextually related by the term within the square brackets.

eg: [game_id] has to be replaced by the identification value of the game, as an int32.

If an IRI is enclosed within double quotes (""), the literal string representation of the URI is assumed.

Definitions

Types

Types is the parent of all protocol objects that are used to transport information. To construct the identifier of 1 element of this container, the first part of the path must equal to types.

kettle:types/[type_name]

eg kettle:types/create_game is the identifier of the CreateGame object.

  • Practical value: Kettle Type Object
  • Underlying type: object
  • Minimum value: N/A
  • Maximum value: N/A
  • Empty: N/A

Accounts

Accounts is the parent of all game accounts that are known and future known by the game database. To construct the identifier of 1 game account, the first part of the path must equal account.

kettle:accounts/[account_id]

eg kettle:accounts/1465140039 is the identifier of the 1 account with 1465140039 as ID-property.

  • Practical value: [account_id]
  • Underlying type: string
  • Minimum value: 1
  • Maximum value: unbound
  • Empty: N/A

Cards

Cards is the parent of all cards from the game. Known and future known. They are known by the game database and simulators. To construct the identifier of 1 card, the first part of the path must equal cards.

kettle:cards/[card_id]

eg kettle:cards/CS2_196 is the identifier of the 1 card whith CS2_196 as CardID-property (= Razorfen Hunter).

  • Practical value: [card_id]
  • Underlying type: string
  • Minimum value: N/A
  • Maximum value: N/A
  • Empty: YES

Games

Games is the parent of all games ever played, being played and played in the future. To construct the identifier of 1 game, the first part of the path must equal games.

kettle:games/[game_id]

eg kettle:games/452155414214 is the identifier of the 1 game with 452155414214 as GameID-property.

  • Practical value: [game_id]
  • Underlying type: string
  • Minimum value: 1
  • Maximum value: unbound
  • Empty: NO

Entities

Entities are all objects that have state within the game. Each game in itself is an entity, so is each hero, heropower and cards. Entity ID's are the way to identify objects with state when the ACTUAL NAME of the entity is hidden. These ID's are set by a monotone counter when the corresponding entity is created by the simulator. Each IRI identifies exactly 1 and the same entity for each possible perspective.

The game itself is also an entity, which will ALWAYS have EntityID 1!

To construct the identifier of 1 entity, the procedure is to build upon the URI for games.

kettle:games/[game_id]/entities/[entity_id]

eg kettle:games/1/entities/250 is the identifier of the 1 entity with 250 as EntityID-property from the 1 game that has 1 as GameID-property.

  • Practical value: [entity_id]
  • Underlying type: int32
  • Minimum value: 1
  • Maximum value: unbound
  • Empty: N/A

Players

Players is the parent of all participants in a game. A player is the owner of a deck of cards and is represented in the game by a hero (card). There are exactly 2 players within each game.

Be aware that the ID of the first player equals 1!

To construct the identifier of 1 player, the procedure is to build upon the URI for games.

kettle:games/[game_id]/players/[player_id]

eg kettle:games/1/players/1 is the identifier of the 1 player with 1 as PlayerID-property from the 1 game that has 1 as GameID-property.

  • Practical value: [player_id]
  • Underlying type: int32
  • Minimum value: 1
  • Maximum value: 2
  • Empty: N/A

Choices

Choices are used in a scenario when a Player is given a set of entities and it has to pick none, 1 or more. Choices are always presented to Players by the simulator and the Player responds after performing his choice.

eg: Mulligan or the 'Discover' effect.

To construct the identifier of 1 choice set presented to the Player, the procedure is to build upon the URI for games.

kettle:games/[game_id]/choices/[choice_id]

eg kettle:games/1/choices/1 is the identifier of the 1 choice set with 1 as ChoiceID-property from the 1 game that has 1 as GameID-property.

  • Practical value: [choice_id]
  • Underlying type: int32
  • Minimum value: 1
  • Maximum value: unbound
  • Empty: N/A

Options

Options are similar to Choices except a Player can only pick exactly 1 of the given set entities. Options are always presented to Players by the simulator and the Player responds after picking an option. Options can have suboptions, which represent the 'Pick one' effect.

It's not allowed for the player to make an empty choice, exactly 1 choice must be selected!

To construct the identifier of 1 option set, the procedure is to build upon the URI for games.

kettle:games/[game_id]/options/[option_id]

eg kettle:games/1/options/1 is the identifier of the 1 option set with 1 as OptionID-property from the 1 game that has 1 as GameID-property.

  • Practical value: [option_id]
  • Underlying type: int32
  • Minimum value: 1
  • Maximum value: unbound
  • Empty: N/A