HL Log Standard

From Valve Developer Community
Jump to navigation Jump to search


Half-Life Standard Log Format Specification

Revision 1.03

This document defines a standard format for log messages for all Half-Life mods to adhere to.

Notice: This document began as a proposal developed by a group of Half-Life server administrators and utility developers, on the hlds_apps mailing list. Valve Software have now implemented this new format (in TFC, CS and HLDM), and it is included in all client/server releases of Half-Life since version 1.1.0.6. This document can now be used as a reference specification for mod authors and utility developers.

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.pngNote: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. In TFC, if tfc_clanbattle is 1, this doesn't happen.
    Server cvars start
  2. This is executed both at the beginning of a round and whenever someone changes a cvar over rcon.
    Server cvar "var" = "value"
  3. In TFC, if tfc_clanbattle is 0, this doesn't happen. You can instead use 005, since it comes right after.
    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

  1. Server name is "hostname"

006. Server Say

  1. Server say "message"

Game

050. Connection

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

050b. Validation

"Name<uid><wonid><>" STEAM USERID validated

051. Enter Game

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

052. Disconnection

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

052b. Kick

Kick: "Name<uid><wonid><>" was kicked by "Console" (message "")

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 property3 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 event3.

"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 property3 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 property3 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.
  2. 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.
  3. 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 (").
  4. 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.
  5. 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><>".
  6. "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).
  7. Duplicate property key names are not allowed.
  8. Empty properties (e.g. ()) or properties with no key name (e.g. ("foo")) are not allowed.
  9. 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

Example 1: Perl: Log parsing routines.

Appendix B - Example Log Files

ChangeLog

1.03
25 Sep 2001 12:45 PM NZT - Added notes 8 (empty properties) and 9 (log comments).
1.02
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).
1.01
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.
1.00
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 <sgarner_gameplanet.co.nz>

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


Implementations

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=HL_Log_Standard&oldid=207962"