Package: quakestats
Quake StatsQuake 3 logs / Quake Live events processing project.Allows to retrieve, process, analyze, store and present Quake matches.The project doesn't aim to give global stats likeqlstatsit's rather meant to store statistics from some server group (server domain). The origins of Quake Stats come from a group of players who occasionally play together and want to keep track of their matches... and to have fun from some custom made medals (badges) :)OverviewSupported features:processing Quake 3 logs (log parsing, transforming to QL)processing Quake Live event streams (zmq listen on QL server stat endpoint)translating (to some extent) Quake 3 logs into Quake Live eventsanalysing matchesstoring matches in Database backend (Mongo DB)presenting match results through a web applicationSupported mods and game modesUnfortunately only OSP FFA from Quake 3 is well tested as it was the main use casemods- OSP (http://www.orangesmoothie.org/tourneyQ3A/index.html)- Quake Live - most of event processing is implemented- Edawn - requires 1.6.3+ (enchanced logging)- vanilla Q3 not supported (need workaround for missing ServerTime)- CPMA not supported (need workaround for missing ServerTime)modes- DUEL- FFA- CA - partially implemented- TDM- CTFCustom medalsAre described hereresources.jsExamplesThe stats are presented with fancy charts, custom medals, etc. See the examples below.Total badges/medals boardTotal kills & deathsSingle match Kill Death Ratio, Worst Enemy, Score over Time chartRequirementsPython 3.6+Instance of Mongo DB (pointed bysettings.py)Modern web browser (requires css grid-layout)How to setupIn order to setup the application you need to have python 3.6+ (virtualenv recommended) and an instance of mongo DB.InstallationInstall from pip packagepipinstallquakestatsInstall from source code (optional)Is also needed installquakestatspackage (in virtualenv if you are using it). To do that you could install it directlypipinstall-rrequirements.txt
pythonsetup.pyinstallConfiguration fileThe application is configured by settingQUAKESTATS_SETTINGSenvironment variable to path to configuration file.
See examplesettings.pyVerify if everything is properly set upQuake Stats provide a simple CLI with a command to verify an environmentquakestatsstatusExample output:(venv) [user@pc quakestats]$ quakestats status
app -> version: 0.9.61
settings -> env var: /opt/quakestats/settings.py
settings -> RAW_DATA_DIR: /opt/quakestats/data
db -> ping: {'ok': 1.0}
webapp -> loadable: Quakestats webapp is loadableRun Quake Stats web appYou can setup Quake Stats web app with any websever you want (as long as it supports python, e.g. mod wsgi, uwsgi).
This documentation covers only running intwistedwebserverRun in twistd (example)You can launch Quake Stats web application usingtwistdwebserver. Just make sure to install twisted framework first.
Also make sure to use some recent version of twisted (tested with 18.7.0 installed by pip).pipinstalltwistedFLASK_APP="quakestats.web";QUAKESTATS_SETTINGS=`pwd`/settings.py;twistdweb--wsgiquakestats.web.appUser/Admin guideSetup admin userAdmin user is used by web application to access some additional administrative operations. For now it's only setting map sizes. Just to have a list of recently used maps and their sizes. Nothing more at the moment.# you need to run the command in proper python environment# use "quakestats status" to check your environmentquakestatsset-admin-pwd<yourpassword>Collecting Quake Live statsQuake Live exposes stats server through tcp socket (zmq) authenticated with password.
CLI can gather stats from multiple QL servers and process them automatically.
Use following config file[server-1]ip=5.6.7.8port=27967password=password1[server-1]ip=1.2.3.4port=27967password=password2Use following CLI to start collecting events (assuming your config file is namedcollector.cfg)quakestatscollect-qlcollector.cfgUploading Quake 3 log fileIn order to process some data you need to send your match log file to web api endpoint/api/v2/upload. By default modospis assumed.
Mod specific endpoint is served under/api/v2/upload/<mod>, e.g./api/v2/upload/edawnYou need anADMIN_TOKENset in configuration.curl-XPOST--formfile=@/path/to/your/games.log--formtoken=adminsecrettokenhost:port/api/v2/uploadAll log files with extracted matches are stored in directory determined byRAW_DATA_DIRconfig entryUsing automated script to send logsTODO, deprecatedRebuilding databaseYou can rebuild your database using files stored inRAW_DATA_DIRwith simple web api call or CLI.curl-XPOSThost:port/api/v2/admin/rebuild--formtoken=adminsecrettoken# you need to run the command in proper python environment# use "quakestats status" to check your environmentquakestatsrebuild-dbIf you implement some new Medals or any other backend related feature this API call will clear previous data stored in DB and process all matches from data directory once again.Merging player resultsUnfortunately the only way to distinguish players in Quake 3 servers is to use player nickname. When player changes his nickname between matches he will be treated as new unique player. In such cases admin can merge results of two specific players. Use with caution as it will rewrite history of all matches stored in database.curl-XPOSThost:port/api/v2/admin/players/merge--formtoken=admintoken--formsource_player_id=297f6272f79d4918c4efe098--formtarget_player_id=df55e5cd4582d6f14cd20746It will merge all results from player with id297f6272f79d4918c4efe098into player with iddf55e5cd4582d6f14cd20746. To find out how player ID is build see the development section.Importing preprocessed match logPreprocessed match logs stored inRAW_DATA_DIRcan be imported using admin match import API.
This can be particularly useful when e.g. debugging some bugs on dev infra.curl-XPOST--formfile=@bugmatch.log--formtoken=admintokenhost:port/api/v2/admin/match/importDevelopmentTech stackPython, Flask, MongoDB, d3.js, riot.js, zmqHow does it work with Quake 3 PlayersQuake 3 players don't have unique ID's so it's hard to distinguish players between matches. In order to overcome this problem each player hasplayer_idassigned during match analysis. The ID is constructed as hash ofSERVER_DOMAINand player nickname as a result it's consistent between matches as long as player keeps his nickname and there is no nickname clash. Perhaps there is some better way? Server side auth?WebWeb application related componentsapi - web API used by frontend and to retrieve Quake 3 logsviews - typical flask viewsExtendingHow to add new medalseeSpecialScores class- for special scoresseeBadger class- for badges calculationseeJS resources- to add new medal imageRunning testsmaketestAssetsMedals, icons, etc.
Some of the assets are missing it would be nice to find some free ones or draw them ;)How to release new versionbumpversion<major|minor|patch>--commit--tag