hearthsim / python-hslog

Python module to parse Hearthstone Power.log files

hslog

hslog is a powerful Hearthstone Power.log deserializer.

Concepts

The data read from Power.log is deserialized into packets. The log is read line by line using a regex-based approach, with packets accumulating data when they span over multiple lines. The BLOCK_START and BLOCK_END packets are serialized into a Block packet, which is nestable. We call the totality of the packets for a game the "Packet Tree".

Exporting a PacketTree

The PacketTree object makes it easy to recursively iterate over, which in turn makes it very easy to export into various other formats. The .export() method on PacketTree will natively export the entire tree to a Game entity, using the hearthstone.entities module by default.

This is achieved through a very flexible class-based Exporter system, which can be found in hslog.export. The syntax to call an exporter directly is: MyExporter(packet_tree).export().

The base logic for the Exporter is in the BaseExporter class. Calling export() will iterate over each packet and call export_packet(packet) on them. That method will look at the packet's type, get the matching method in the self.dispatch dict (populated by get_dispatch_dict()) and call it on it.

This is the default dispatch lookup:

• CreateGame -> handle_create_game()
• CreateGame.Player: handle_player()
• Block: handle_block
• FullEntity: handle_full_entity
• HideEntity: handle_hide_entity
• ShowEntity: handle_show_entity
• ChangeEntity: handle_change_entity
• TagChange: handle_tag_change
• MetaData: handle_metadata
• Choices: handle_choices
• SendChoices: handle_send_choices
• ChosenEntities: handle_chosen_entities
• Options: handle_options
• Option: handle_option
• SendOption: handle_send_option
• ResetGame: handle_reset_game
• SubSpell: handle_sub_spell

All of the methods in the dispatch dict should be implemented.

Exporting the game state

The default exporter used by PacketTree is the EntityTreeExporter. It creates an "Entity Tree" by simulating each packet in its handler. Choices, Options and MetaData packets are ignored.

The entity tree is a hearthstone.entities.Game object. It contains a list of entities in the entities attribute, which themselves have tags in their tags attribute.

The export fully simulates every available packet. The game state at the end of the export is therefore the state of the game at the end of the parsed log file.

Exporting the friendly player

Conceptually, a game does not have a friendly player. We can think of a game as the server-side object, which is sent to two separate players. However, a Power.log file does have a friendly player: The bottom player, whose cards are revealed.

The FriendlyPlayerExporter class allows exporting the friendly player. The exporter works by looking through the initial tag changes and full entity packets, attempting to figure out which "side" is getting cards revealed that could only happen if the player is friendly.

This behaviour is undefined when the log contains a "double-spectate" (both sides of the games spectated at the same time).

License

This project is licensed under the MIT license. The full license text is available in the LICENSE file.

Community

This is a HearthSim project. Join the HearthSim developer community to participate.

python-hslog's Issues

Battlegrounds - How to get the board's state at the beginning of combat

Hi,

I want to collect both players' minions at the start of the battle phase on Battlegrounds. I periodically read the Power.log and want to detect when the phases change and all minions have been created for combat.

How do I know when the log contains all the entities for combat?

Implement game reset

RESET_GAME / GAME_RESET. Needs further investigation.

Usage example

Could you provide an example of using this package?

hslog.player.InconsistentPlayerIdError whenever I play more than one game

my power.log file doesn't get parsed when I play more than game without closing hearthstone. I tried to solve this issue but couldn't figure out how to do it.

Also I get a lot of "WARNING:root:[08:39:42.582806] Broken option nesting. Working around..." before getting inconsistentPlayerIdError.

OS: macOS 13.0.1

Fix missing entity in TargetOption

The following options block from this power.log contains a player name not matching the Battletag. The generated HSReplay file is therefore missing the entity attribute on the Target block.

D 23:49:45.8759909 GameState.DebugPrintOptions() -   option 1 type=POWER mainEntity=[name=Gadgetzan Socialite id=43 zone=HAND zonePos=1 cardId=CFM_659 player=2] error=NONE errorParam=
D 23:49:45.8759909 GameState.DebugPrintOptions() -     target 0 entity=[name=Anduin Wrynn id=64 zone=PLAY zonePos=0 cardId=HERO_09 player=1] error=NONE errorParam=
D 23:49:45.8759909 GameState.DebugPrintOptions() -     target 1 entity=[name=Magni Bronzebeard id=66 zone=PLAY zonePos=0 cardId=HERO_01a player=2] error=NONE errorParam=
D 23:49:45.8759909 GameState.DebugPrintOptions() -     target 2 entity=[name=Emerald Reaver id=47 zone=PLAY zonePos=1 cardId=UNG_803 player=2] error=NONE errorParam=
D 23:49:45.8759909 GameState.DebugPrintOptions() -     target 3 entity=[name=Bloodsail Corsair id=33 zone=PLAY zonePos=1 cardId=NEW1_025 player=1] error=NONE errorParam=
D 23:49:45.8759909 GameState.DebugPrintOptions() -     target 4 entity=GameEntity error=REQ_HERO_OR_MINION_TARGET errorParam=
D 23:49:45.8759909 GameState.DebugPrintOptions() -     target 5 entity=dan conley error=REQ_HERO_OR_MINION_TARGET errorParam=
D 23:49:45.8764913 GameState.DebugPrintOptions() -     target 6 entity=Carrot error=REQ_HERO_OR_MINION_TARGET errorParam=
D 23:49:45.8764913 GameState.DebugPrintOptions() -     target 7 entity=[name=Lesser Heal id=65 zone=PLAY zonePos=0 cardId=CS1h_001 player=1] error=REQ_HERO_OR_MINION_TARGET errorParam=
D 23:49:45.8764913 GameState.DebugPrintOptions() -     target 8 entity=[name=Armor Up! id=67 zone=PLAY zonePos=0 cardId=CS2_102_H1 player=2] error=REQ_HERO_OR_MINION_TARGET errorPar

HSReplay document with missing entity attribute on <Target/>:

<Option EntityName="Gadgetzan Socialite" entity="43" index="1" type="3">
	<Target EntityName="Anduin Wrynn" entity="64" index="0"/>
	<Target EntityName="Magni Bronzebeard" entity="66" index="1"/>
	<Target EntityName="Emerald Reaver" entity="47" index="2"/>
	<Target EntityName="Bloodsail Corsair" entity="33" index="3"/>
	<Target entity="1" error="33" index="4"/>
	<Target error="33" index="5"/>
	<Target entity="3" error="33" index="6"/>
	<Target EntityName="Lesser Heal" entity="65" error="33" index="7"/>
	<Target EntityName="Armor Up!" entity="67" error="33" index="8"/>
</Option>

The resulting XML cannot be reimported using HSReplayDocument.from_xml_file, since it erros with the following stacktrace:

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
helpers.py:126: in __init__
    self.exporter = get_exporter_from_replay(path, is_power_log)
helpers.py:111: in get_exporter_from_replay
    packet_tree = replay.to_packet_tree()[0]
../../../redshift-env/lib/python3.4/site-packages/hsreplay/document.py:71: in to_packet_tree
    ret.append(game.export())
../../../redshift-env/lib/python3.4/site-packages/hsreplay/elements.py:90: in export
    tree.packets.append(node.export())
../../../redshift-env/lib/python3.4/site-packages/hsreplay/elements.py:343: in export
    packet.options.append(node.export(i))
../../../redshift-env/lib/python3.4/site-packages/hsreplay/elements.py:360: in export
    packet.options.append(node.export(i))
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

self = <OptionTargetNode>, id = 5

    def export(self, id):
            optype = "target"
            type = None
            packet = self.packet_class(
>                   self.ts, int(self.entity), id, type, optype,
                    self.error, self.errorParam
            )
E           TypeError: int() argument must be a string or a number, not 'NoneType'

../../../redshift-env/lib/python3.4/site-packages/hsreplay/elements.py:392: TypeError

Unhandled CHANGE_ENTITY due to missing card id

Looks like we're losing track of some card id. This seems to only affect Monster Hunter games where Toki, or the final boss Toki is in play.

https://sentry.io/hearthsim/hsreplaynet-lambdas/issues/537416952

Test HSLog during DST change

@jleclanche commented on Tue Jun 07 2016