{"id":18451958,"url":"https://github.com/brabiega/quakestats","last_synced_at":"2025-06-27T14:07:31.041Z","repository":{"id":48118353,"uuid":"128992002","full_name":"brabiega/quakestats","owner":"brabiega","description":"Quake 3 Arena / Quake Live match processing app","archived":false,"fork":false,"pushed_at":"2024-04-08T16:09:52.000Z","size":1504,"stargazers_count":18,"open_issues_count":15,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-11T22:03:04.186Z","etag":null,"topics":["osp","quake","quake3","quakelive","stats"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brabiega.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.MD","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-10T20:37:20.000Z","updated_at":"2022-12-10T17:21:42.000Z","dependencies_parsed_at":"2023-02-17T14:00:54.212Z","dependency_job_id":"30a93270-fe7b-4855-89bb-a079163ccbae","html_url":"https://github.com/brabiega/quakestats","commit_stats":{"total_commits":278,"total_committers":3,"mean_commits":92.66666666666667,"dds":"0.017985611510791366","last_synced_commit":"d08975ba8ce30a6d830ec60e7848693b5c1a8331"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/brabiega/quakestats","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brabiega%2Fquakestats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brabiega%2Fquakestats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brabiega%2Fquakestats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brabiega%2Fquakestats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brabiega","download_url":"https://codeload.github.com/brabiega/quakestats/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brabiega%2Fquakestats/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262270427,"owners_count":23285165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["osp","quake","quake3","quakelive","stats"],"created_at":"2024-11-06T07:29:49.637Z","updated_at":"2025-06-27T14:07:31.014Z","avatar_url":"https://github.com/brabiega.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quake Stats\n[![PyPI](https://img.shields.io/pypi/v/quakestats)](https://pypi.org/project/quakestats/)\n[![PyPI - Wheel](https://img.shields.io/pypi/wheel/quakestats)](https://pypi.org/project/quakestats/#files)\n\nQuake 3 logs / Quake Live events processing project.\n\nAllows to retrieve, process, analyze, store and present Quake matches.\n\nThe project doesn't aim to give global stats like [qlstats](http://qlstats.net) it'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) :)\n\n## Overview\n### Supported features:\n* processing Quake 3 logs (log parsing, transforming to QL)\n* processing Quake Live event streams (zmq listen on QL server stat endpoint)\n* translating (to some extent) Quake 3 logs into Quake Live events\n* analysing matches\n* storing matches in Database backend (Mongo DB)\n* presenting match results through a web application\n\n### Supported mods and game modes\nUnfortunately only OSP FFA from Quake 3 is well tested as it was the main use case\n#### mods\n- [x] - OSP (http://www.orangesmoothie.org/tourneyQ3A/index.html)\n- [x] - Quake Live - most of event processing is implemented\n- [x] - Edawn - requires 1.6.3+ (enchanced logging)\n- [ ] - vanilla Q3 not supported (need workaround for missing ServerTime)\n- [ ] - CPMA not supported (need workaround for missing ServerTime)\n\n#### modes\n- [x] - DUEL\n- [x] - FFA\n- [ ] - CA - partially implemented\n- [ ] - TDM\n- [ ] - CTF\n\n### Custom medals\nAre described here [resources.js](quakestats/static/js/resources.js)\n\n### Examples\nThe stats are presented with fancy charts, custom medals, etc. See the examples below.\n#### Total badges/medals board\n![home1](examples/home1.png)\n#### Total kills \u0026 deaths\n![home2](examples/home2.png)\n#### Single match Kill Death Ratio, Worst Enemy, Score over Time chart\n![match1](examples/match1.png)\n\n### Requirements\n- Python 3.6+\n- Instance of Mongo DB (pointed by ```settings.py```)\n- Modern web browser (requires css grid-layout)\n\n## How to setup\nIn order to setup the application you need to have python 3.6+ (virtualenv recommended) and an instance of mongo DB.\n\n### Installation\n#### Install from pip package\n```bash\npip install quakestats\n```\n\n#### Install from source code (optional)\nIs also needed install ```quakestats``` package (in virtualenv if you are using it). To do that you could install it directly\n```bash\npip install -r requirements.txt\npython setup.py install\n```\n\n### Configuration file\nThe application is configured by setting ```QUAKESTATS_SETTINGS``` environment variable to path to configuration file.\nSee example [settings.py](examples/settings.py)\n\n### Verify if everything is properly set up\nQuake Stats provide a simple CLI with a command to verify an environment\n```bash\nquakestats status\n```\n\nExample output:\n```\n(venv) [user@pc quakestats]$ quakestats status\napp -\u003e version: 0.9.61\nsettings -\u003e env var: /opt/quakestats/settings.py\nsettings -\u003e RAW_DATA_DIR: /opt/quakestats/data\ndb -\u003e ping: {'ok': 1.0}\nwebapp -\u003e loadable: Quakestats webapp is loadable\n```\n\n### Run Quake Stats web app\nYou can setup Quake Stats web app with any websever you want (as long as it supports python, e.g. mod wsgi, uwsgi).\nThis documentation covers only running in *twisted* webserver\n\n#### Run in twistd (example)\nYou can launch Quake Stats web application using ```twistd``` webserver. Just make sure to install twisted framework first.\nAlso make sure to use some recent version of twisted (tested with 18.7.0 installed by pip).\n```bash\npip install twisted\nFLASK_APP=\"quakestats.web\"; QUAKESTATS_SETTINGS=`pwd`/settings.py; twistd web --wsgi quakestats.web.app\n```\n\n## User/Admin guide\n### Setup admin user\nAdmin 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.\n```bash\n# you need to run the command in proper python environment\n# use \"quakestats status\" to check your environment\nquakestats set-admin-pwd \u003cyourpassword\u003e\n```\n\n### Collecting Quake Live stats\nQuake Live exposes stats server through tcp socket (zmq) authenticated with password.\nCLI can gather stats from multiple QL servers and process them automatically.\nUse following config file\n\n```ini\n[server-1]\nip = 5.6.7.8\nport = 27967\npassword = password1\n\n[server-1]\nip = 1.2.3.4\nport = 27967\npassword = password2\n\n```\n\nUse following CLI to start collecting events (assuming your config file is named ```collector.cfg```)\n\n```bash\nquakestats collect-ql collector.cfg\n```\n\n### Uploading Quake 3 log file\nIn order to process some data you need to send your match log file to web api endpoint ```/api/v2/upload```. By default mod ```osp``` is assumed.\nMod specific endpoint is served under ```/api/v2/upload/\u003cmod\u003e```, e.g. ```/api/v2/upload/edawn```\nYou need an ```ADMIN_TOKEN``` set in configuration.\n```bash\ncurl -X POST --form file=@/path/to/your/games.log --form token=adminsecrettoken host:port/api/v2/upload\n```\n\nTo send vanila q3 log use\n```\ncurl -X POST --form file=@/path/to/your/games.log --form token=adminsecrettoken host:port/api/v2/upload/baseq3\n```\n\nTo send edawn log use\n```\ncurl -X POST --form file=@/path/to/your/games.log --form token=adminsecrettoken host:port/api/v2/upload/edawn\n\n```\nAll log files with extracted matches are stored in directory determined by ```RAW_DATA_DIR``` config entry\n\n### Using automated script to send logs\nTODO, deprecated\n\n### Rebuilding database\nYou can rebuild your database using files stored in ```RAW_DATA_DIR``` with simple web api call or CLI.\n```bash\ncurl -X POST host:port/api/v2/admin/rebuild --form token=adminsecrettoken\n```\n```bash\n# you need to run the command in proper python environment\n# use \"quakestats status\" to check your environment\nquakestats rebuild-db\n```\nIf 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.\n\n### Merging player results\nUnfortunately 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.\n```bash\ncurl -X POST host:port/api/v2/admin/players/merge --form token=admintoken --form source_player_id=297f6272f79d4918c4efe098 --form target_player_id=df55e5cd4582d6f14cd20746\n```\nIt will merge all results from player with id ```297f6272f79d4918c4efe098``` into player with id ```df55e5cd4582d6f14cd20746```. To find out how player ID is build see the development section.\n\n### Importing preprocessed match log\nPreprocessed match logs stored in ```RAW_DATA_DIR``` can be imported using admin match import API.\nThis can be particularly useful when e.g. debugging some bugs on dev infra.\n```bash\ncurl -X POST --form file=@bugmatch.log --form token=admintoken host:port/api/v2/admin/match/import\n```\n\n## Development\n### Tech stack\nPython, Flask, MongoDB, d3.js, riot.js, zmq\n\n##### How does it work with Quake 3 Players\nQuake 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 has ```player_id``` assigned during match analysis. The ID is constructed as hash of ```SERVER_DOMAIN``` and 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?\n\n#### Web\nWeb application related components\n- api - web API used by frontend and to retrieve Quake 3 logs\n- views - typical flask views\n\n### Extending\n#### How to add new medal\n- see [SpecialScores class](quakestats/dataprovider/analyzer/specials.py) - for special scores\n- see [Badger class](quakestats/dataprovider/analyzer/badges.py) - for badges calculation\n- see [JS resources](quakestats/static/js/resources.js) - to add new medal image\n\n#### Running tests\n```bash\nmake test\n```\n### Assets\nMedals, icons, etc.\nSome of the assets are missing it would be nice to find some free ones or draw them ;)\n\n### How to release new version\n```bash\nbumpversion \u003cmajor|minor|patch\u003e --commit --tag\n```\n\n## Troubleshooting\n### Can't use mongodb 5.0+ without AVX on Ubuntu 20+\nThis problem occurs on older hardware when mongodb 5.0+ is being used.\nYou can't use official mongodb packages with version higher than 4.x. 4.x series is the last one not using AVX. BUT it requires libssl1.1 and it's no longer shipped with Ubuntu.\nFortunately it's possible to install libssl1.1 from http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/. Then just install mongodb 4.x.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrabiega%2Fquakestats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrabiega%2Fquakestats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrabiega%2Fquakestats/lists"}