Half-Life Standard Log Format Specification
Revision 1.03

Intended Audience

This document is aimed at anyone involved with HL logging or log parsing -- Valve Software, mod authors and developers, utility developers, etc.

Goals

• To define a set of events which cover all existing and imaginable mods' needs, and exactly what the format of those events should look like.
• To ensure a common format for each event so that parsers do not need to be mod-specific. Ideally, it should be possible for utilities to be compatible with any mod, even mods that the utility author has never tested with, or mods which have not been created yet.
• Log messages should be human readable. Not every admin is going to use a program or script to sort through their log files.
• Log messages for the various events should use a consistent style.
• Event formats should be somewhat extensible to allow for the potential needs of future games.
• Event formats should be unambiguous (such that a regular expression can be constructed to reliably retrieve all fields from the log message) and all information about an event should be contained in a single log line.

Note The L mm/dd/yyyy - hh:mm:ss: timestamp prefix on log messages is omitted from all format specifications below.

Events - HL Engine

• 001. Cvars

  1. Server cvars start

  2. Server cvar "var" = "value"

  3. Server cvars end

• 002. Log Files

  1. Log file started (file "filename") (game "game") (version "protocol/release/build")

  2. Log file closed

• 003. Change Map
  1. This event replaces the current "Spawning server" message.

     Loading map "map"

  2. This event replaces the current "Map CRC" message. The message should appear AFTER all PackFile messages, to indicate when the game actually commences.

     Started map "map" (CRC "crc")

• 004. Rcon

  1. Rcon: "rcon challenge "password"  command" from "ip:port"

  2. Bad Rcon: "rcon challenge "password"  command" from "ip:port"

• 005. Server Name

  Server name is "hostname"

• 006. Server Say

  Server say "message"

Events - Game

• 050. Connection

  "Name<uid><wonid><>" connected, address "ip:port"

• 051. Enter Game

  "Name<uid><wonid><>" entered the game

• 052. Disconnection

  "Name<uid><wonid><team>" disconnected

• 053. Suicides

  "Name<uid><wonid><team>" committed suicide with "weapon"

• 054. Team Selection

  "Name<uid><wonid><team>" joined team "team"

• 055. Role Selection
  This event covers classes in games like TFC, FLF and DOD.

  "Name<uid><wonid><team>" changed role to "role"

• 056. Change Name

  "Name<uid><wonid><team>" changed name to "Name"

• 057. Kills

  "Name<uid><wonid><team>" killed "Name<uid><wonid><team>" with "weapon"

• 058. Injuring
  This event allows for recording of partial kills and teammate friendly-fire injuries. The suggested damage property³ could be used to show how much health the victim lost. If the injury results in a kill, a Kill message (057) should be logged instead/also.

  "Name<uid><wonid><team>" attacked "Name<uid><wonid><team>" with "weapon" (damage "damage")

• 059. Player-Player Actions
  This event allows for logging of a wide range of events where one player performs an action on another player. For example, in TFC this event may cover medic healings and infections, sentry gun destruction, spy uncovering, etc. More detail about the action can be given by appending more properties to the end of the event³.

  "Name<uid><wonid><team>" triggered "action" against "Name<uid><wonid><team>"

• 060. Player Objectives/Actions

  "Name<uid><wonid><team>" triggered "action"

• 061. Team Objectives/Actions

  Team "team" triggered "action"

• 062. World Objectives/Actions
  This event allows logging of anything which does not happen in response to the actions of a player or team. For example a gate opening at the start of a round.

  World triggered "action"

• 063. Chat

  1. "Name<uid><wonid><team>" say "message"

  2. "Name<uid><wonid><team>" say_team "message"

• 064. Team Alliances

  Team "team" formed alliance with team "team"

• 065. Round-End Team Score Report

  Team "team" scored "score" with "numplayers" players

  Use the property³ mechanism to extend this event where necessary. Some standard property key names to use for this event have been defined as follows:

  • kills
  • kills_unaccounted
  • deaths
  • deaths_unaccounted
  • allies (list using <team>... notation)
  • captures

  Example:

  Team "Yellow" scored "73" with "5" players (kills "182")
  (kills_unaccounted "4") (deaths "217") (allies "<Red><Green>")

• 066. Private Chat

  "Name<uid><wonid><team>" tell "Name<uid><wonid><team>" message "message"

• 067. Round-End Player Score Report

  Player "Name<uid><wonid><team>" scored "score"

  Use the property³ mechanism to extend this event where necessary. Some standard property key names to use for this event have been defined as follows:

  • kills
  • kills_unaccounted
  • deaths
  • deaths_unaccounted

  Example:

  Player "Joe<123><654321><123>" scored "54" (kills "36") (deaths "11")

• 068. Weapon Selection
  Use this event to show what weapon a player currently has selected.

  "Name<uid><wonid><team>" selected weapon "weapon"

• 069. Weapon Pickup
  

  "Name<uid><wonid><team>" acquired weapon "weapon"

Notes

1. For non-teamplay games, team should be equal to uid.
   • Team codes may be numbers or strings (strings are recommended), but may not contain the angle bracket characters < and > (less than and greater than) to avoid parsing ambiguities.

   • Event formats may be extended by adding additional (key "value") properties onto the end of the log message. Utility authors should allow for this when parsing. key names may not contain spaces or parentheses (( or )). A value may not contain double-quotes (").

   • Parenthised properties with no explicit value indicate a boolean true value. If the property is missing a false value may be assumed. For example, a mod might use:

     "Name<uid><wonid><team>" killed "Name<uid><wonid><team>" with "weapon" (headshot)

     The presence of (headshot) would indicate a true value for the headshot property.

   • For some events (e.g. 054. Team Selection) the player may or may not already be in a team. If the player is not in a team, the player's team name should be an empty string, i.e. the player would look like "Name<uid><wonid><>".

   • "World" can be represented in any player event by specifying the player identifier as: "<-1><><>" - i.e. use empty string for the Name, wonid and team, and -1 as uid. However, this should only be done if there is no applicable World or Team event format (e.g. 062, 061).

   • Duplicate property key names are not allowed.

   • Empty properties (e.g. ()) or properties with no key name (e.g. ("foo")) are not allowed.

   • A log message may be marked as a comment by preceding it with the double-slash comment marker, // (after the timestamp). These lines can be used by mods to provide additional human-readable information in the log. Such lines should be completely ignored by parsers. For example (for clarity, the timestamp is shown in this example):

     L 09/24/2001 - 18:44:50: // This is a comment in the log file. It should not be parsed.

Appendix A - Code Examples

1. Example Perl code

Appendix B - Example Log Files

1. Counter-Strike
2. Team Fortress 1.5

ChangeLog

• 25 Sep 2001 12:45 PM NZT - Added notes 8 (empty properties) and 9 (log comments).

• 24 Sep 2001 12:05 PM NZT - Added note 7 about duplicate property key names.
• 23 Sep 2001 02:25 PM NZT - Added events 067 (Round End Player Score), 068 (Weapon Selection) and 069 (Weapon Pickup).

• 28 Mar 2001 10:30 AM NZT - Changed numbering scheme so that new events can be added without renumbering in the future - HL Engine events are now numbered from 001 to 049, Game events from 050 to 099. Added 066. Private Chat (client 'tell' command) and 006. Server Say (server 'say' command) event formats.

• 21 Mar 2001 12:00 PM NZT - Added example log files for Team Fortress 1.5. (Thanks to Nathan Woodcock for contributing these files.)
• 16 Mar 2001 12:40 PM NZT - Added example log files for Counter-Strike.
• 16 Mar 2001 12:30 PM NZT - Updated regular expressions in Example 1 (Perl code). Now uses [^"\(]+ for text outside quotes, to not match (key "value") properties.
• 16 Mar 2001 12:20 PM NZT - Updated Rcon (20) event format to match Valve's implementation.

Comments to Simon Garner <>

Last modified 2001-09-25 12:58:42 NZST