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 Nameproperty (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 Typeproperty;
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

Homestone's Fireplace communication snippet

Stove's Kettle communication snippet