https://github.com/hearthsim/python-hslog

Python module to parse Hearthstone Power.log files
https://github.com/hearthsim/python-hslog

hearthstone log-parser parsing regex

Last synced: about 24 hours ago
JSON representation

Python module to parse Hearthstone Power.log files

• Host: GitHub
• URL: https://github.com/hearthsim/python-hslog
• Owner: HearthSim
• License: mit
• Created: 2017-04-16T11:04:03.000Z (over 7 years ago)
• Default Branch: main
• Last Pushed: 2024-10-28T20:47:24.000Z (about 2 months ago)
• Last Synced: 2024-12-14T10:06:13.887Z (8 days ago)
• Topics: hearthstone, log-parser, parsing, regex
• Language: Python
• Homepage: https://hearthsim.info
• Size: 199 KB
• Stars: 62
• Watchers: 13
• Forks: 13
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# hslog

[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/HearthSim/python-hslog/ci.yml?branch=main)](https://github.com/HearthSim/python-hslog/actions/workflows/ci.yml)

[![PyPI](https://img.shields.io/pypi/v/hslog.svg)](https://pypi.org/project/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](https://hearthsim.info) project.

[Join the HearthSim developer community](https://hearthsim.info/join/) to participate.