tf-logparser

A TypeScript parser for Team Fortress 2 server logs. Parses raw TF2 log files into typed, structured event objects using a Peggy grammar.

Usage

import { parseLog } from "tf-logparser";
import type { RawTfLogEvent } from "tf-logparser";

const raw = fs.readFileSync("match.log", "utf-8");
const events: RawTfLogEvent[] = parseLog(raw);

Every event includes a timestamp (ms since epoch) and a 1-based lineNumber into the original log. Events are discriminated by the type field, so you can narrow with a simple check:

for (const event of events) {
  if (event.type === "kill") {
    console.log(
      `${event.player.name} killed ${event.victim.name} with ${event.weapon}`,
    );
  }
}

Log format spec

Each line in a TF2 server log follows this structure:

L MM/DD/YYYY - HH:MM:SS: <event data>

Player format

Players are encoded as:

"<name><<entityId>><<steamId>><<team>>"

For example: "Frank<52><[U:1:156276611]><Red>"

Parsed into:

interface Player {
  name: string;
  entityId: number;
  steamId: string;
  team: string;
}

Supported event types

The parser recognizes the following events. Any line that doesn't match a known pattern is returned as an unknown event.

Combat

Type	Attributes	Description
damage	player, victim, damage, weapon, realdamage?, crit?, headshot?, airshot?, height?, healing?	Player damaged another player.
kill	player, victim, weapon, attackerPosition, victimPosition, customkill?	Player killed another player.
killAssist	player, victim, assisterPosition, attackerPosition, victimPosition	Player assisted a kill.
suicide	player, weapon, attackerPosition	Player killed themselves.
medicDeath	player, victim, healing, ubercharge	Medic was killed.
medicDeathEx	player, uberpct	Extended medic death info.
playerExtinguished	player, victim, weapon, attackerPosition, victimPosition	Player extinguished a burning teammate.
shotFired	player, weapon	Player fired a weapon.
shotHit	player, weapon	Player's shot hit a target.

Healing & Ubercharge

Type	Attributes	Description
healed	player, target, healing, airshot?, height?	Medic healed a target.
chargeReady	player	Medigun charge is ready.
chargeDeployed	player, medigun	Ubercharge deployed.
chargeEnded	player, duration	Ubercharge ended.
emptyUber	player	Ubercharge fully depleted.
firstHealAfterSpawn	player, time	Time of first heal after medic spawned.
lostUberAdvantage	player, time	Medic lost uber advantage.

Objectives

Type	Attributes	Description
pointCaptured	team, cp, cpname, numcappers, players[]	Team captured a control point.
captureBlocked	player, cp, cpname, position	Player blocked a capture.

Buildings & Objects

Type	Attributes	Description
playerBuiltObject	player, object, position	Player built an object.
killedObject	player, object, weapon, objectowner, attackerPosition, assist?, assisterPosition?	Player destroyed an object.
objectDetonated	player, object, position	Player detonated their own object.
playerCarryObject	player, object, position	Player picked up their building.
playerDropObject	player, object, position	Player dropped their building.

Round & Game

Type	Attributes	Description
roundStart	—	Round started.
roundSetupBegin	—	Setup phase began.
roundSetupEnd	—	Setup phase ended.
roundWin	winner	Round won by a team.
roundLength	seconds	Round duration in seconds.
roundOvertime	—	Overtime started.
roundStalemate	—	Round ended in a stalemate.
gameOver	reason	Game ended.
currentScore	team, score, numPlayers	Mid-game score report.
finalScore	team, score, numPlayers	End-of-game score report.
intermissionWinLimit	team	Intermission or win limit reached.

Player State

Type	Attributes	Description
spawned	player, role	Player spawned as a class.
spawnedMFilter	player, role?	Player spawned with m_filter.
changedRole	player, role	Player changed class.
changedName	player, newName	Player changed their name.
chargedMFilter	player, role	Player charged as role with m_filter.
pickedUpItem	player, item, healing?	Player picked up an item.
joinedTeam	player, newTeam	Player joined a team.
connected	player, address	Player connected to the server.
disconnected	player, reason	Player disconnected.
steamUserIdValidated	player	Player's Steam ID was validated.
enteredGame	player	Player entered the game.
positionReport	player, position	Player position report.

Domination & Revenge

Type	Attributes	Description
domination	player, victim, assist?	Player is dominating another.
revenge	player, victim, assist?	Player got revenge.

Chat

Type	Attributes	Description
say	player, message	Public chat message.
sayTeam	player, message	Team chat message.

Pause

Type	Attributes	Description
matchPause	player	Player triggered a pause.
matchUnpause	player	Player triggered an unpause.
gamePaused	—	Game is paused.
gameUnpaused	—	Game is unpaused.
pauseLength	seconds	Pause duration in seconds.

Passtime

Type	Attributes	Description
passGet	player, firstcontact, position	Player got the ball.
passFree	player, position	Ball became free.
passPassCaught	player, target, interception, save, handoff, dist, duration, throwerPosition, catcherPosition	Pass was caught.
passScore	player, points, panacea, winStrat, deathbomb, dist, position	Player scored.
passScoreAssist	player, position	Player assisted a score.
passBallStolen	player, victim, stealDefense, thiefPosition, victimPosition	Ball was stolen.
catapult	player, catapult, position	Player used a catapult.
passtimeBallSpawned	location	Ball spawned at a location.
passtimeBallDamage	details	Ball took damage.
panaceaCheck	details	Panacea check event.

System

Type	Attributes	Description
serverPluginMessage	plugin, message	Message from a server plugin (e.g. demos.tf, SteamNetworkingSockets).
worldMetaData	key, value	Match metadata (matchid, map, title).
meta	label, kvs	Meta comment line (e.g. # COMBINED_LOG).
printingForClient	client	Server printing for a client.
unknown	body	Unrecognized log line (fallback).

Benchmarks

Measured on real match logs (median of 20 runs after 3 warmup runs):

Fixture	Size	Lines	Time	Lines/sec
cp.log	1601 KB	12692	154.6 ms	82,119
koth.log	1147 KB	8519	91.6 ms	93,030
passtime.log	1246 KB	10260	185.9 ms	55,189
payload.log	1463 KB	11066	133.4 ms	82,982
ultiduo.log	285 KB	2172	25.0 ms	86,763

Run benchmarks yourself with:

npm run build:parser && npx tsx scripts/benchmark.ts

Tested game modes

The parser is tested against real log fixtures for:

• Control Points (5CP)
• King of the Hill
• Payload
• Passtime
• Ultiduo

Note: This project targets the TF2 log format from 2025 onward and does not aim to support older log formats.

Contributing

See CONTRIBUTING.md for how to add or fix event parsers, including how to add test fixtures for lines that break the parser.

Development

npm run build          # Generate parser + compile TypeScript
npm test               # Build parser + run tests
npm run test:watch     # Run tests in watch mode
npm run lint           # Lint source
npm run format         # Format with Prettier

License

ISC