README

Parse The Crucible game logs into a structured model.

Requirements

PHP >= 8.4

Installation

Install via Composer:

composer require adnanmula/keyforge-game-log-parser

Quick start

<?php

use AdnanMula\KeyforgeGameLogParser\Event\EventType;
use AdnanMula\KeyforgeGameLogParser\Parser\GameLogParser;
use AdnanMula\KeyforgeGameLogParser\Parser\ParseType;

$log = file_get_contents('path/to/log.txt');

$parser = new GameLogParser();
$game = $parser->execute($log, ParseType::PLAIN);

$winner = $game->winner()?->name;
$keysForged = $game->timeline()->filter(EventType::KEY_FORGED)->count();
$reapsByPlayer1 = $game->player1->timeline->filter(EventType::REAP)->count();
$firstCreatureUsedToReapByPlayer1 = $game->player1->timeline->filter(EventType::REAP)->at(0)->value;

Input formats

You can parse logs provided in 3 different formats via ParseType:

ParseType::PLAIN (default): a single string containing the full log, what you get when use tco's copy to clipboard button.
ParseType::ARRAY: an array of strings containing the log messages, one per line.
ParseType::HTML: the HTML markup of the log view.

<?php

use AdnanMula\KeyforgeGameLogParser\Parser\GameLogParser;
use AdnanMula\KeyforgeGameLogParser\Parser\ParseType;

$parser = new GameLogParser();

$plainString = '
    Alice brings Deck A to The Crucible
    Bob brings Deck B to The Crucible
    ...
';

// PLAIN
$game1 = $parser->execute($plainString, ParseType::PLAIN);

// ARRAY
$messages = [
    'Alice brings Deck A to The Crucible',
    'Bob brings Deck B to The Crucible',
    // ...
];
$game2 = $parser->execute($messages, ParseType::ARRAY);

// HTML
$html = '<div class="message">Alice brings Deck A to The Crucible</div>...';
$game3 = $parser->execute($html, ParseType::HTML);

Exploring results

execute() returns a Game object with the following useful members:

player1, player2 (AdnanMula\KeyforgeGameLogParser\Game\Player)
- name, deck, isFirst, isWinner, hasConceded
- timeline (AdnanMula\KeyforgeGameLogParser\Game\Timeline)
winner(): ?Player
loser(): ?Player
first(): ?Player (the player who took the first turn)
timeline(): Timeline (combined, time-ordered events from both players)

Timelines are collections with helper methods:

filter(EventType ...$events): Collection
count(), first(), last(), at(int $i), items(): array

Example queries:

<?php

use AdnanMula\KeyforgeGameLogParser\Event\EventType;

// Checks declared across the whole game
$checks = $game->timeline()->filter(EventType::CHECK_DECLARED)->items();

// Player-specific timeline queries
$p1Checks = $game->player1->timeline->filter(EventType::CHECK_DECLARED)->items();
$p2Keys   = $game->player2->timeline->filter(EventType::KEY_FORGED)->items();
$reapsAndFights   = $game->player2->timeline->filter(EventType::REAP, EventType::FIGHT)->items();

etc...

Events

The library categorizes log messages into typed events via EventType enum:

AMBER_OBTAINED
AMBER_STOLEN
CARDS_DISCARDED
CARDS_DRAWN
CARDS_PLAYED
CARD_USED
HOUSE_CHOSEN
KEY_FORGED
FIGHT
REAP
EXTRA_TURN
TOKEN_CREATED
PROPHECY_ACTIVATED
PROPHECY_FULFILLED
FATE_RESOLVED
TIDE_RAISED
CHAINS_ADDED
CHAINS_REDUCED
PLAYER_CONCEDED
CHECK_DECLARED

adnanmula / keyforge-game-log-parser

Maintainers

Details