2. Kettle IRI - HearthSim/kettle-design GitHub Wiki
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