Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

LANCommander Match Statistics for Metamod

Reports the matches played on a GoldSrc (Half-Life engine) game server to LANCommander's match statistics. Each report covers who played, what happened (kills, objectives, rounds, chat) and how the match ended. LANCommander builds leaderboards from these reports and links in-game players to its users.

It is a Metamod plugin. It is the sibling of LANCommander.SourceMod.MatchStatistics and LANCommander.QMM.MatchStatistics, and reports the same events and statistics under the same names.

Delivery is handled by the LANCommander Interposer, which is built into the plugin.

  • It sends events in batches.
  • It retries while LANCommander can't be reached.
  • It keeps anything unsent on disk, so a crash, restart or network outage loses nothing.

Games

One plugin binary serves every game. It picks the game's module from the game directory.

Game Directory What is recorded
Counter-Strike 1.6 and Condition Zero (Valve's DLL or ReGameDLL_CS) cstrike, czero Kills (weapon, headshots, teamkills, world deaths), rounds with their winner and reason, bomb plants, defuses and explosions, hostages, the VIP, team scores (rounds won) and standings. Warmup (Game_Commencing) is not recorded.
Day of Defeat 1.3 dod Kills, flag and area captures, objectives (TNT, carried objects), classes, rounds won (from the team scores), the objective score.
Team Fortress Classic tfc Kills, flag pickups, captures, drops and returns, map goals, sentries, dispensers and teleporters built, upgraded and destroyed, medic heals and cures, spies discovered, classes, team scores.
Natural Selection 3.x ns Each game on a map is its own match. Kills (teamkills too), structures built and destroyed, research, commanders taking and leaving the chair, classes, the winning side, scores. Classic and combat.
Half-Life deathmatch and teamplay valve Kills (teamplay teamkills too), frags, team scores (teamplay), standings.
Ricochet ricochet Kills (decapitations, bounces), arena rounds and battles won, frags.
Any other Metamod game As Half-Life: kills from the standard log lines, frags, and the end of the game.

James Bond 007: Nightfire is not supported yet: its engine's interface differs from the HLSDK's throughout, so it needs a build of its own. See Nightfire.

What has been run. Condition Zero (Linux) has been run end to end with bots. The other modules are written against each game's released code or binaries (see Building) and unit-tested with the lines and messages those games send, but have not been run on a server yet.

Installing

  1. Install Metamod. Metamod-P works with today's HLDS (the 25th anniversary update). Point the game's liblist.gam at it (gamedll_linux "addons/metamod/dlls/metamod.so", gamedll "addons\metamod\dlls\metamod.dll"), or use Metamod-R on ReHLDS.

  2. Copy the plugin. Put the release's addons/lancommander/ folder into the game directory (cstrike/, dod/, ...), and add it to addons/metamod/plugins.ini:

    linux addons/lancommander/dlls/lancommander_mm_i386.so
    win32 addons/lancommander/dlls/lancommander_mm.dll
    
  3. Create a token. In LANCommander, open Profile → Access Tokens and create a token with Report matches (the matches:report scope). Create it under an administrator account if the reports should count as authoritative.

  4. Configure the server. Copy lancommander.cfg next to server.cfg, fill it in, and exec lancommander.cfg from server.cfg:

    lc_server_url "http://lancommander.lan:1337"
    lc_token      "lc_pat_..."
    lc_game_id    "6f1e2c64-0d47-4b8e-9a43-3a1c2bde0f11"
    
  5. Start the server. lc_status on the server console (or through rcon) shows the match being recorded and how delivery is going.

Linux servers can only use http://. The Interposer's Linux HTTP client has no TLS. LANCommander on a LAN is normally plain HTTP. Linux needs glibc 2.36 or newer (Debian 12, Ubuntu 22.10 or later, and LANCommander's own game server images).

HLDS is 32-bit, on Linux and Windows, and so is the plugin.

Configuration

Where reports go

Cvar Default
lc_enabled 1 0 records nothing.
lc_server_url The LANCommander server.
lc_token A personal access token with the matches:report scope. %VARIABLE% reads an environment variable, so the token can be kept out of the config file. The cvar is protected: its value is never shown to clients.
lc_game_id The game's id in LANCommander (a GUID).
lc_server_id This server's id in LANCommander, if LANCommander manages it.
lc_reporter_name hostname How the server is named in LANCommander.
lc_flush_interval 2000 Milliseconds between batches of events.

The plugin reads these cvars about once a second. A change applies to the next match.

What a match is

Cvar Default
lc_min_players 1 Human players needed before a match opens. Bots don't count.
lc_mode The mode reported. Empty lets the game's module decide (defusal, teamplay, classic, combat, arena, ...).
lc_settings_cvars per game Cvars kept with each match as its settings, e.g. mp_timelimit,mp_maxrounds,mp_friendlyfire.

When a match starts. Once enough players are in and the game is past its warmup: CS's first round with both teams manned, NS's game start after the countdown.

When it ends. At game over: the intermission (mp_timelimit, mp_fraglimit, mp_maxrounds, ...), or NS's victory. If the map changes first, the match ends with it.

Restarts. A game that starts over without a new map wipes its scores, so the match is abandoned and a new one opens: CS's sv_restart and Game_Commencing, TFC's end of prematch, an NS game reset with no winner.

What is recorded

Cvar Default
lc_record_bots 1 Bots as players (bot:<name>).
lc_record_chat 0 Chat messages (say, say_team).
lc_record_positions 1 Player positions in kill and objective events, and the distance.
lc_record_damage 0 Every hit as a damage event, where the game logs hits (CS with mp_logdetail 3, NS with mp_logdetail 1). Damage totals are kept either way.
lc_events_include Records only these event types. Comma-separated, * as a wildcard. Empty records every type.
lc_events_exclude Never records these event types. Applied after lc_events_include.

Filtering leaves statistics alone. The lc_events_* filters affect only which individual events are recorded. With kill excluded, kills, deaths and the standings are still counted.

Admin commands (server console or rcon)

Command
lc_status The match being recorded, where it is sent, what is still waiting, and the last delivery problem.
lc_flush Sends what is waiting now. Blocks the server for up to 5 s.
lc_startmatch [mode] Starts a match now, ignoring lc_min_players and warmup.
lc_endmatch [reason] Ends the match. No new match starts until the next map.
lc_abandonmatch Ends the match as abandoned, so its results don't count.

Players

A player key names a player to LANCommander for the whole match:

  • steam:STEAM_0:1:123: a Steam account.
  • bot:<name>: a bot.
  • name:<name>: a player with no Steam id (STEAM_ID_LAN, VALVE_ID_LAN). This is the usual case at a LAN party with sv_lan 1.

A Steam id still pending is waited for up to 10 seconds. The key is fixed then, so a rename does not split a player in two. HLTV proxies are not players.

Events and statistics

Every game.

  • Events: kill, team_change, name_change, disconnect, chat (optional), damage (optional), game_end (with the winning team).
  • Statistics: kills, deaths, suicides, teamkills, headshots (CS), hits, damage_dealt, damage_taken, team_damage (where hits are logged), score, time_played_ms.

Kills. The kill event carries the weapon as the game logs it, headshot, suicide, world (falls, trigger_hurt), teamkill, positions and distance.

Game modules. The events and statistics each module adds:

  • Counter-Strike: round_start, round_end (winner, reason, score_ct, score_t), bomb_planted/bomb_plants, bomb_defused/bomb_defuses, bomb_exploded/bomb_explosions, bomb_begindefuse, bomb_pickup, bomb_dropped, hostage_follows, hostage_rescued/hostages_rescued, hostage_killed/hostages_killed, hostages_rescued_all, vip_spawn, vip_escaped/vip_escapes, vip_killed/vip_kills, terrorist_escaped/terrorist_escapes; team rounds_won.
  • Day of Defeat: point_captured/captures, area_captured, object_pickup, object_captured/objectives, class_change, round_end (winner, points, team scores); team rounds_won, captures.
  • Team Fortress Classic: flag_pickup/flag_pickups, flag_captured/flag_captures, flag_dropped, flag_returned/flag_returns, goal/goals (map goals, named by the map), building_built, building_upgraded, building_repaired, building_destroyed, building_dismantled (with the building), detpack_set, detpack_disarmed, heal/heals, cure/cures, infection, spy_discovered, tranquilised, concussed, class_change.
  • Natural Selection: class_change, commander_start, commander_end, structure_built, structure_destroyed, structure_recycled, research_started, research_cancelled, commander_votedown.
  • Ricochet: arena_round_won/arena_rounds_won, arena_battle_won/arena_battles_won; kills carry decapitated and bounces.

Standings.

  • Team games rank the teams by score; each player takes their team's place, Finished for the winners and Defeated for the rest. A team's score is what the game keeps: rounds won in CS, points in DoD and TFC, the frags of its players in HL teamplay. NS ranks by the winning side.
  • Free-for-all ranks players by score (frags).
  • A player who left before the end is DidNotFinish.

How events are read. GoldSrc games write their log lines (Valve's "HL Log Standard": "Pat<2> <STEAM_0:1:123><CT>" killed ...) through the engine, and the plugin reads them as they are written. log on is not needed. The rest comes from the messages the game sends its clients (TeamInfo, TeamScore, DeathMsg, ScoreInfo, the intermission) and from the player entities. Nothing is read from the game DLL's private data, so the plugin works with ReGameDLL and with other mods that keep the stock log lines and messages.

Where things are kept

The Interposer works from .interposer/ next to the plugin (addons/lancommander/dlls/.interposer/):

  • Logs/: a session log per server start. Add Logging: { Matches: true } to .interposer/Config.yml to log every report.
  • Matches/: reports not yet delivered. They are sent on the next start once the cvars are set, and removed once LANCommander has them.

The plugin pins itself in memory when it loads, so that a meta unload or meta reload cannot pull the code from under the Interposer's delivery thread. An unload mid-map ends the match there.

Nightfire

James Bond 007: Nightfire runs on Gearbox's own fork of the engine. Its enginefuncs_t differs from the HLSDK's from the start (its own console variable API, functions added and moved), so this plugin's binary cannot load there. Supporting it needs a second build against Nightfire's headers (click4dylan/Nightfire_SDK), whose author notes they match the stock 1.0/1.1 game but not the 5.9x community patch that LANCommander's Nightfire server image runs. That build needs a 5.9x install to check its interface against.

Building

CMake and vcpkg build the plugin. The HLSDK, Metamod (for its plugin API headers) and the Interposer are git submodules:

git submodule update --init --recursive
export VCPKG_ROOT=/path/to/vcpkg

# Windows (Visual Studio 2022 or later, v143 toolset); YY-Thunks is needed by the Interposer's CMake
powershell -File external/LANCommander.Interposer/build/Get-YYThunks.ps1
cmake --preset windows-x86 && cmake --build --preset windows-x86-release

Linux builds run inside the Interposer's build image (Debian 12, x86 multilib):

docker build -f external/LANCommander.Interposer/docker/build.Dockerfile -t lancommander-interposer-build external/LANCommander.Interposer/docker
docker run --rm -v "$PWD:/src" -w /src lancommander-interposer-build sh -c '
  cmake --preset linux-x86 && cmake --build --preset linux-x86-release'

Build options.

  • -DLC_CORE_ONLY=ON builds only the game-neutral core, the game modules and their unit tests: no SDK, no Interposer, no vcpkg.
  • To build against a working copy of the Interposer, add -DLANCOMMANDER_INTERPOSER_DIR=/path/to/LANCommander.Interposer.

Tests.

  • ctest --preset <preset> runs the unit tests: the log parser, the match lifecycle against a fake game, every game module against a fake engine (with the lines and messages each game sends), the standings and the JSON payloads.
  • What each game logs and sends is recorded, with its sources (file and line in the released code, or offsets in the closed binaries), in docs/research/.
  • End to end. tests/e2e/fake_lancommander.py stands in for LANCommander and logs every request; tests/e2e/run_hlds.sh runs a Linux HLDS with Metamod-P and the plugin in Docker; summarize.py reports on what arrived.

Licence

GPLv3. See LICENSE.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages