{"id":20236788,"url":"https://github.com/th3-z/kf2-magicked-admin","last_synced_at":"2025-04-10T19:11:19.986Z","repository":{"id":54863552,"uuid":"104470697","full_name":"th3-z/kf2-magicked-admin","owner":"th3-z","description":":spider: Mutator-free management, statistics, and in-game bot for ranked Killing Floor 2 servers","archived":false,"fork":false,"pushed_at":"2022-08-05T14:17:45.000Z","size":1946,"stargazers_count":32,"open_issues_count":20,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-24T16:52:06.549Z","etag":null,"topics":["bot","chatbot","kf2","killingfloor2","player-commands","player-stats","statistics"],"latest_commit_sha":null,"homepage":"https://kf2-ma.th3-z.xyz","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/th3-z.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-22T12:13:36.000Z","updated_at":"2024-07-27T18:08:33.000Z","dependencies_parsed_at":"2022-08-14T05:01:10.479Z","dependency_job_id":null,"html_url":"https://github.com/th3-z/kf2-magicked-admin","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/th3-z%2Fkf2-magicked-admin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/th3-z%2Fkf2-magicked-admin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/th3-z%2Fkf2-magicked-admin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/th3-z%2Fkf2-magicked-admin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/th3-z","download_url":"https://codeload.github.com/th3-z/kf2-magicked-admin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248279678,"owners_count":21077408,"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":["bot","chatbot","kf2","killingfloor2","player-commands","player-stats","statistics"],"created_at":"2024-11-14T08:23:17.712Z","updated_at":"2025-04-10T19:11:19.959Z","avatar_url":"https://github.com/th3-z.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg width=125 height=125 src=\"https://files.th3-z.xyz/standing/kf2-ma.png\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eKilling Floor 2 Magicked Admin\u003c/h1\u003e\n\n[![Downloads](https://img.shields.io/github/downloads/th3-z/kf2-magicked-admin/total.svg)](https://img.shields.io/github/downloads/th3-z/kf2-magicked-admin/total.svg) [![Build Status](https://travis-ci.com/th3-z/kf2-magicked-admin.svg?branch=master)](https://travis-ci.com/th3-z/kf2-magicked-admin) [![Coverage Status](https://coveralls.io/repos/github/th3-z/kf2-magicked-admin/badge.svg?branch=master)](https://coveralls.io/github/th3-z/kf2-magicked-admin?branch=master) [![CodeFactor](https://www.codefactor.io/repository/github/th3-z/kf2-magicked-admin/badge/master)](https://www.codefactor.io/repository/github/th3-z/kf2-magicked-admin/overview/master) [![GitHub license](https://img.shields.io/github/license/th3-z/kf2-magicked-admin)](https://github.com/th3-z/kf2-magicked-admin/blob/master/LICENSE)\n\n\n\nAbout\n-----\n\nScripted management, statistics, and bot for ranked Killing Floor 2 servers. \nProvides in-game commands, player stat tracking and ranking, live MOTD \nscoreboard and stats, greeter, and admin functions. Running entirely through \nthe web admin, it does not affect a server's ranked/custom status. It can be \nran either directly on the server or remotely, and manage multiple servers at \nonce.\n\nDownloads\n---------\n\nThe most recent stable version is `0.1.6`. A binary is provided on the releases page for Windows and Linux users. \n\n[Release 0.1.6](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.6)\n\n\u003cdetails\u003e\n\u003csummary\u003eOld releases\u003c/summary\u003e\n\t\n* [Release 0.1.5](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.5)\n* [Release 0.1.4](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.4)\n* [Release 0.1.3](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.3)\n* [Release 0.1.2](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.2)\n* [Release 0.0.7](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.0.7)\n\u003c/details\u003e\n\nFeatures\n--------\n\n### Commands\n\nWhen inputting commands into the chat they need to be prefixed with `!`.\nWhen writting commands into a script, or chaining them this should be \nomitted. \n\nMany commands will look for closest matches to their parameters. \nFor example '_biotics_' will match '_kf-biotics-lab_' and '_userO_' will match\n'_userOne™/@:®_'.\n\nAll commands have in-game help text that can be accessed with the `-h` flag.\n\n* Example: `!commands -h`\n\nAll commands also have the following flags.\n\n* `-q` - Suppresses output\n* `-p` - Pads output to hide the username line\n\nEscape sequences as follows are available to format messages.\n\n* `\\n` - Newline\n    - Example: `!say line 0\\nline 1`\n* `\\t` - Tab\n    - Example: `!say line 0\\n\\tline 1 is indented`\n\n#### Player commands\n\nCommands that can be executed by any player.\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to see the player commands!\u003c/summary\u003e\n\t\n* `!commands` - Shows a list of all commands available to players\n* `!stats \u003cuser\u003e` - Shows general statistics about a user\n    - Example: `!stats` Shows stats about yourself\n    - Example: `!stats the_z` Shows stats about the_z\n* `!kills \u003cuser\u003e` - Shows kill statistics about a user\n    - Example: `!kills` Shows kill stats about yourself\n    - Example: `!kills the_z` Shows kill stats about the_z\n* `!dosh \u003cuser\u003e` - Shows dosh statistics about a user\n    - Example: `!dosh` Shows dosh stats about yourself\n    - Example: `!dosh the_z` Shows dosh stats about the_z\n* `!time \u003cuser\u003e` - Shows time statistics about a user\n    - Example: `!dosh` Shows time stats about yourself\n    - Example: `!dosh the_z` Shows time stats about the_z\n* `!map` - Shows statistics about the current map\n* `!record_wave` - Shows the highest wave achieved on the current map\n* `!top_kills` - Shows the global kills leaderboard\n* `!top_dosh` - Shows the global dosh leaderboard\n* `!top_time` - Shows the global play time leaderboard\n* `!top_wave_kills` - Shows information about who killed the most ZEDs \n                      in the current wave. Generally for use with `start_trc`\n    - Example: `!start_trc -- top_wave_kills`\n* `!top_wave_dosh` - Shwows information about who earned the most dosh in \n                     the current wave. Generally for use with `!start_trc`\n    - Example: `!start_trc -- top_wave_dosh`\n* `!server_kills` - Shows total kills on the server\n* `!server_dosh` - Shows total dosh earned on the server\n* `!scoreboard` - Shows the complete player scoreboard, useful on servers with \u003e6 max players\n    - Alias: `!sb` Does the same\n* `!game` - Shows information about the current game\n* `!maps [--all]` - Shows the current map cycle\n    - Option `-a`: Show all available maps\n* `!player_count` - Shows the player count and max players\n\u003c/details\u003e\n\n#### Admin commands\n\nCommands that can be ran by server administrators or users authorized with \nthe `!op` command.\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to see the admin commands!\u003c/summary\u003e\n\t\n* `!op \u003cuser\u003e` - Gives a user administrative rights\n    - Example: `!op the_z`\n* `!deop \u003cuser\u003e` - Revokes a user's administrative rights\n    - Example: `!deop the_z`\n* `!say \u003cmessage\u003e` - Echoes a message into chat\n    - Example: `!say The quick brown fox jumps over the lazy dog`\n    - Example: `!start_trc -- say The trader is open`\n* `!players` - Shows detailed information about players on the server\n* `!kick \u003cuser\u003e` - Kicks `\u003cuser\u003e` from the match\n    - Example: `!kick the_z`\n* `!ban \u003cuser\u003e` - Bans `\u003cuser\u003e` from the server\n    - Example: `!ban the_z`\n    - Warnng: The web admin currently has a bug that causes bans to persist\n      after they are deleted, thus there is no unban command\n* `!length \u003clength\u003e` - Change the length to `\u003clength\u003e` next game\n    - Example: `!length short`\n* `!difficulty \u003cdifficulty\u003e` - Change the difficulty to `\u003cdifficulty\u003e` next \n                               game\n    - Example: `!difficulty hell`\n* `!game_mode \u003cgame_mode\u003e` - Immediately change the game mode to `\u003cgame_mode\u003e`\n    - Example: `!game_mode endless` Changes the game mode to Endless\n* `!load_map \u003cmap\u003e` - Immediately change the map to `\u003cmap\u003e`\n    - Example: `!load_map biotics` Changes the map to Biotics Lab\n* `!restart` - Immediately restart the current game\n* `!password [--set] \u003con|off\u003e`\n    - Example: `!password on` Enables the game password defined in the config\n    - Example: `!password off` Disables the game password\n    - Example: `!password --set somePass` Sets a specific password\n* `!start_jc [-r] -- \u003ccommand\u003e` - Start a command that runs every time a player joins\n        - `-r` Only run for returning players\n\t- Example: `!start_jc -- say Welcome %PLR` - Greets a player on join\n\t- Available tokens: `%PLR` - username, `%KLL` - total kills, `%DSH` - \n      total dosh; `%PLR` - username, `%BCK` - \"back\" if sessions \u003e 1, `%DRK` - \n      dosh rank, `%KRK` - kill rank, `%TME` - play time, `%TRK` - play time \n      rank, `%SES` - sessions\n* `!stop_jc` - Stops all join commands\n* `!start_wc [-w \u003cwave\u003e] -- \u003ccommand\u003e` - Start a command that runs on wave `\u003cwave\u003e`\n    - `-w` Wave to run the command on, can be omitted to have the command\n    run every wave\n    - `-w` Can be negative to count backwards from the boss wave\n    - Example: `!start_wc -1 -- say Welcome to the boss wave`\n* `!stop_wc` - Stops all wave commands\n* `!start_tc [-r, -t \u003cseconds\u003e] -- \u003ccommand\u003e` - Start a command that runs after\n    `\u003cseconds\u003e` seconds\n    - Option `-r`: Add to have the command run repeatedly\n    - Option `-t`: Required, the number of seconds before the command runs\n    - Example: `!start_tc -rt 600 -- say Join our Steam group!\\n\n\thttp://steam.group/`\n* `!stop_tc` - Stops all timed commands\n* `!start_trc [-w \u003cwave\u003e] -- \u003ccommand\u003e` - Start a commands that runs when the trader opens\n    - `-w` Wave to run the command on, can be omitted to have the command\n        run every wave\n    - `-w` Can be negative to count backwards from the boss wave\n    - Example: `!start_trc -- top_wave_dosh` - Shows who earned the most dosh \n\tevery wave when the trader opens\n* `!stop_trc` - Stop all commands that run on trader open\n* `!silent` - Toggles suppression of all chat output, commands still have \n              effect, but the response will not be visible to players\n* `!run \u003cscript_name\u003e` - Executes a script from the `conf/scripts` folder, more\n                         information in the scripts section\n    - Example: `!run example`\n* `!marquee \u003cmarquee_name\u003e` - Runs a marquee in the chat from the\n                              `conf/marquee` folder, _experimental_\n    - Example: `!marquee example`\n* `!update_motd \u003ctype\u003e` - Refreshes the welcome screen leaderboard, type is \n                          one of: kills, dosh, or time\n    - Example: `!start_tc 300 -- update_motd kills`\n* `!reload_motd` - Reloads the server's `*.motd` file from `conf`\n* `!alias` - Check the help text `!alias -h`\n* `!enforce_dosh \u003camount\u003e` - Kicks all players that have more dosh than the specified `amount`\n    - Example: `!start_tc 600 -- enforce_dosh 60000`\n\u003c/details\u003e\n\n### MOTD leaderboard\n\nA sample `.motd` file is provided in `conf/`. The filename should match the server's name as\nspecified in `conf/magicked_admin.conf`. The template format is Jinja2. An example follows, \nplease refer to the [Jinja2 designer documentation](https://jinja.palletsprojects.com/en/2.11.x/templates/).\n```\nWelcome to our server.\n\n{{ millify(server_kills) }} Zeds killed on this server.\n\nTop Players (total dosh):\n{% for player in top_dosh[0:9] -%}\n    {{loop.index}}. {{player.username|truncate(11)}} [{{millify(player.score)}}]\t\t{% if loop.index is divisibleby 3 %}\n{% endif %}\n{%- endfor %}\n\nHave fun and good luck!\n```\n\n### Scripts\n\nWriting a `server_name.init` in the `conf/scripts` folder with a series of commands\nwill run the commands in sequence when the bot starts on `server_name`.\n\nAdditional scripts can be written in the `conf/scripts` folder and ran with the\n`!run` command. There is an example already in there that can be ran with \n`!run example`.\n\n* Comments can be added to scripts by prefixing a line with `;`.\n\n### Webadmin patches\n\nFor gamemodes other than survival to function in full patches have to be\napplied to the `KFGame/Web/ServerAdmin` folder on the server. For this reason\na script is provided in the `admin-patches` folder that will automatically\npatch your server.\n\nThere is currently no CLI or Windows build for this component. You can run it\nwith `python3 admin-patches/admin-patches.py`. A dialogue box will appear\nasking you to locate your server.\n\n\nConfiguration options\n---------------------\n\nBasic setup is done on the first run. However this does not cover all of the \noptions KF2-MA can offer. Please see the config file, `conf/magicked_admin.conf`, \nfor more configuration options as some features are disabled by default.\n\nEach server managed by KF2-MA has a section that looks something like \n`[server_one]`, followed by several options (`x = y`). Copy and edit the\ndefault server section if you want to manage multiple servers. `[server_one]`\nis the name of the server, this can be changed to whatever you want.\n\n### Options\n\nOptions can be configured in the config file `conf/magicked_admin.conf`.\n\n* `address`\n    - Web address of the server's webadmin panel. Requires scheme and protocol,\n    e.g. `https://0.0.0.0:8080`\n* `username`\n    - Webadmin username to login with, this will appear in the chat when the \n    bot has something to output. It's recommended to create a separate account\n    for the bot.\n* `password`\n    - Webadmin password that matches the username above.\n* `game_password`\n    - Default game password to set when the password is toggled using \n    `!password \u003con|off\u003e`.\n* `refresh_rate`\n    - Integer value, webadmin polling rate\n    \nRunning with Docker\n---------------------------\n\nRunning with docker is easy. Just issue this command:\n```\n    docker run -it -p 1880:1880 --name kf2-magicked-admin -v '\u003chost config folder location\u003e':'/magicked_admin/conf' th3z/kf2-magicked-admin\n```\nYou will need to change `\u003chost config folder location\u003e` to wherever you want\nto store your config folder. `/mnt/user/appdata/kf2-magicked-admin` is a popular\nchoice for systems running Unraid.\n\nAfter this command runs the container will exit out and the logs will tell you\nto setup the config file. Go to your `conf` folder and set things up then run \nthe container again and you are good to go!\n\nIf you want to use the admin_patches so that kf-magicked-admin gets installed into your server directory when the container starts (some gamemodes wont track stats without it) just mount your game directory into the container and set the `PATCHES_TARGET_DIR` env variable to the directory. You can mount multiple directories and just separate them with a comma \",\" in the env variable if you have many servers. Here is an example:\n```\n    docker run -it -p 1880:1880 --name kf2-magicked-admin -v '\u003chost config folder location\u003e':'/magicked_admin/conf' -v '\u003chost kf folder\u003e':/kf2-server -v '\u003chost kf folder\u003e':/kf2-server-two -e 'PATCHES_TARGET_DIR'='/kf2-server,/kf2-server-two' th3z/kf2-magicked-admin\n```\n\nRunning from Python sources\n---------------------------\n\nBefore contributing code you will need to install the Python requirements.\n\n### Requirements\nExamples work on Debian 10 and Ubuntu Xenial, may differ for other operating \nsystems. Install the following packages.\n\n* Python 3.7 - `apt install python3`\n* Pip - `apt install python3-pip`\n* Pybabel - `apt install python3-babel`\n* Python 3 dependencies - `pip3 install -r requirements.txt`\n    - This might complain about cx\\_freeze not installing if you haven't got \n    zlib-dev, but cx_freeze is only needed for building.\n\n### Running \n`git clone https://github.com/th3-z/kf2-magicked-admin.git`\n\n`cd kf2-magicked-admin`  \n\n`pip3 install -r requirements.txt`\n\n`make i18n-compile`\n\n`python3 -O magicked_admin/magicked_admin.py`  \n\nThe `-O` flag runs the program in release mode, remove it to run KF2-MA in \ndebug mode. Debug mode will enable more detailed output.\n\nBuilding\n--------\n\nYou can build a binary release for distribution with `make` after installing \nboth the run and build requirements. \n\n### Requirements\nExamples work on Debian 10 and Ubuntu Xenial, may differ for other operating \nsystems.\n\n* Python 3.7 - `apt install python3`\n* Pybabel - `apt install python3-babel`\n* Pip - `apt install python3-pip`\n* Pip dependencies - `pip3 install -r requirements.txt`\n* Make - `apt install make`\n\nOn Windows it's recommend to build with Cygwin. However you can also build it\nby running `python3 setup.py build`. Check the makefile for help building the locale files.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fth3-z%2Fkf2-magicked-admin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fth3-z%2Fkf2-magicked-admin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fth3-z%2Fkf2-magicked-admin/lists"}