7. Game history - HearthSim/kettle-design GitHub Wiki
Relations
- GetGameState -> HistoryBlock | Player -> GameServer
- HistoryBlock :- History/CreateGame
- HistoryBlock :- History/FullEntity
- HistoryBlock :- History/ShowEntity
- HistoryBlock :- History/ChangeEntity
- HistoryBlock :- History/HideEntity
- HistoryBlock :- History/TagChange
- HistoryBlock :- History/PowerBlock
- HistoryBlock :- History/MetaData
Types
GetGameState
GetGameState
is the first object sent from Player to GameServer after Player joined his game.
It asks the GameServer for actions/interactions that happened, to synchronize it's local gamestate.
{
"type": "kettle:types/get_game_state",
"get_game_state":
{
// Empty object
}
}
HistoryBlock
kettle:types/history_block
is an object containing a series of events that occurred as a result of player/entity actions.
Be aware that this object contains a LIST of nested objects!
History block are NOT allowed to be nested!
Valid history objects are are all types contained by the IRI types/history/
path:
kettle:types/history/create_game
: Only allowed at the beginning of the first HistoryBlock per game!kettle:types/history/full_entity
kettle:types/history/show_entity
kettle:types/history/change_entity
kettle:types/history/hide_entity
kettle:types/history/tag_change
kettle:types/history/power_block
kettle:types/history/meta_data
{
"type": "kettle:types/history_block",
"history_block":
[
kettle:types/history/..,
kettle:types/history/..,
..
]
}
History/FullEntity - History/ShowEntity - History/ChangeEntity
kettle:types/history/full_entity
is used to create an entity that is NOT a player AND NOT the game, so a card.
It's not required for an entity to have a set Name
property, in which case the entity is considered HIDDEN.
If the Name
property is set, it's value contents are kettle:cards/[card_id]
and the entity is considered SHOWN.
kettle:types/history/show_entity
is used to fill in the Name
property (and possible other tags) to a given
entity in order to reveal it to Player(s).
kettle:types/history/change_entity
is used to change the Name
property (and possible other tags) of the entity.
The 'minion transform' effect is a usage example of this object.
These object types are 'structural equivalent' to each other. The same object structure can be used for all three types!
-
EntityID: Identifier of the entity. Practically this is the value of a monotone clock at the moment the entity was created by the simulator;
-
Name: The string representation of the Card ID, if known. A hidden/non-revealed entity has an empty value for Name;
-
Tags: List of properties of the entity. The current state of the entity is composed of the default state updated with information from this list. See
kettle:types/Tag
for more information.
{
"type": "kettle:types/history/full_entity",
"full_entity":
{
/*REQ*/ "entityID" := kettle:games/[game_id]/entities/[entity_id],
/*REQ*/ "name" := kettle:cards/[card_id],
/*REQ*/ "tags" :=
[
kettle:types/tag, kettle:types/tag, ..
]
}
}
History/HideEntity
kettle:types/history/hide_entity
hides the specified entity into the set zone.
- EntityID: Identifier of the entity;
- Zone: Indicates which zone the entity will be moved into. TODO: Replace with enum of all possible zones
{
"type": "kettle:types/history/hide_entity",
"hide_entity":
{
/*REQ*/ "entityID" := kettle:games/[game_id]/entities/[entity_id],
/*REQ*/ "zone" := integer,
}
}
History/TagChange
kettle:types/history/tag_change
changes 1 tag value for 1 specific entity.
- EntityID: Identifier of the entity;
- Tag: The numeric value of the updated tag;
- Value: The numeric value assigned to the dereferenced
Tag
property. Boolean like values are written as 0 (false) and 1 (true).
{
"type": "kettle:types/history/tag_change",
"tag_change":
{
/*REQ*/ "entityID" := kettle:games/[game_id]/entities/[entity_id],
/*REQ*/ "tag" := integer,
/*REQ*/ "value" := integer,
}
}
History/CreateGame
kettle:types/history/create_game
represents the point in time when the game was created, including details about players.
Be aware that 'the game itself' is also an entity!
- GameEntity: Information about the game, represented as an entity;
- Players: List of all Player objects, that were installed in the game after game creation.
See
kettle:types/players
for more information.
{
"type": "kettle:types/history/create_game",
"create_game":
{
/*REQ*/ "game_entity" := kettle:games/[game_id]/entities/1, // The game entity is always 1!
/*REQ*/ "players" :=
[
kettle:types/player,
kettle:types/player,
..
]
}
}
History/PowerBlock
kettle:types/history/power_block
is an object containing history objects with information about entity actions and triggers that
need to be played by the animation system on the client. Be aware that this object contains a LIST of nested objects!
Nested kettle:types/history/power_block
are ALLOWED!
Valid history objects are following:
kettle:types/history/full_entity
kettle:types/history/tag_change
kettle:types/history/meta_data
kettle:types/history/power_block
TODO: Check the Choices part.
- PowerType: The type of trigger that initiates the chain of events [~Type];
- EntityID: The EntityID that triggers the effect [~Source];
- CardID: The Name (string value of card tag) of the entity [~EffectCardID];
- EffectIndex: The numeric index of the effect of the card [~Index]; -1 indicates not set
- EntityTarget: The EntityID that serves as target for the animation. [~Target] Defaults to 0 when no target is needed
{
"type": "kettle:types/history/power_block",
"power_block":
{
/*REQ*/ "power_type" := PowerType:integer,
/*REQ*/ "entityID" := kettle:games/[game_id]/entities/[entity_id],
/*OPT*/ "cardID" := kettle:cards/[card_id],
/*REQ*/ "effect_index" := integer,
/*REQ*/ "entity_target" := kettle:games/[game_id]/entities/[entity_id],
}
}
History/MetaData
kettle:types/history/meta_data
is an object that supports tag changes by triggering contextual correct animations on
clients. An example usage of this object would be a triggered healing from 1 entity onto 1 or more other.
- Type: Indicates the semantic meaning of this object;
- Data: Parameter of the effect. This value is semantically different per
Type
property; - Info: List of entityID's that undergo the effect.
{
"type": "kettle:types/history/meta_data",
"meta_data":
{
/*REQ*/ "type" := MetaType:integer, // DEFAULTS TO `TARGET`
/*OPT*/ "data" := integer,
/*REQ*/ "info":
[
kettle:games/[game_id]/entities/[entity_id],
kettle:games/[game_id]/entities/[entity_id],
..
]
}
}
Enums
PowerType
PowerType
is used to give semantic value to kettle:types/history/power_block
.
This value could be seen as the one trigger that causes a chain of effects on several entities in the game.
The values are written in HEX format and the underlying type is int32.
0x0
Invalid.
0x1
Attack. Following events are the result of 1 entity attacking another.
0x2
Joust. Following events are the result of the joust process.
0x3
Power. Following events are actions performed by the entity itself. The trigger is almost anytime playing a card from hand into the battlefield. Examples are choose one, battlecries, inspire or buffs/debuffs for the duration the entity is in play.
0x5
Trigger. Following events are the result of an event listener on an entity. The source entity could be anything (eg: the game, players, minions, secrets..).
0x6
Deaths. Following events are the result of the death processing of an entity.
0x7
Play. Following events are the result of playing an entity.
0x8
Fatigue. Following events are the result of a fatigue tick.
0x9
Ritual. Following events are the result of buffing C'Thun.
MetaType
MetaType
is used to give semantic value to kettle:types/history/meta_data
.
Meta data does not influence the state of the game, but it improves the user experience.
Values are written in HEX format and the underlying type is int32.
0x0
Target. Also the default case.
General animation for one entity interacting with one or more others.
Info
property contains the entityID's of the targets.
0x1
Damage. Plays the damage effect on the target entity.
Data
property contains the amount of damage done.
0x2
Healing. Plays the healing effect on the target entity.
Data
property contains the amount of healing done.
0x3
Joust. Plays the joust effect.
Data
property contains the entityID of the card winning the Joust.
0x5
Show big card. This animation shows a card above the board. The size of this card is bigger than the size in hand. It can be seen next to the history ticker of the game, after Play action. if the card is a secret, it could also be seen around the hero portrait on trigger or destruction.
0x6
Effect timing. Non-MetaData.
0x7
History target. Adds an affected entity to the last history block.
Affected entities have had a certain change in state.
Info
property contains 1 EntityID that must be added to the last history block.
An object with MetaType Override history
must preceed this object before the change can actually occur!
0x8
Override history. Erases all resulting effects from the entire last history block.
Other sources
All known tags from the HearthStone client