Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/th3-z/kf2-magicked-admin
:spider: Mutator-free management, statistics, and in-game bot for ranked Killing Floor 2 servers
https://github.com/th3-z/kf2-magicked-admin
bot chatbot kf2 killingfloor2 player-commands player-stats statistics
Last synced: 2 months ago
JSON representation
:spider: Mutator-free management, statistics, and in-game bot for ranked Killing Floor 2 servers
- Host: GitHub
- URL: https://github.com/th3-z/kf2-magicked-admin
- Owner: th3-z
- License: mit
- Created: 2017-09-22T12:13:36.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-08-05T14:17:45.000Z (over 2 years ago)
- Last Synced: 2023-10-20T23:23:10.642Z (over 1 year ago)
- Topics: bot, chatbot, kf2, killingfloor2, player-commands, player-stats, statistics
- Language: Python
- Homepage: https://kf2-ma.th3-z.xyz
- Size: 1.86 MB
- Stars: 29
- Watchers: 9
- Forks: 6
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Killing Floor 2 Magicked Admin
[](https://img.shields.io/github/downloads/th3-z/kf2-magicked-admin/total.svg) [](https://travis-ci.com/th3-z/kf2-magicked-admin) [](https://coveralls.io/github/th3-z/kf2-magicked-admin?branch=master) [](https://www.codefactor.io/repository/github/th3-z/kf2-magicked-admin/overview/master) [](https://github.com/th3-z/kf2-magicked-admin/blob/master/LICENSE)
About
-----
Scripted management, statistics, and bot for ranked Killing Floor 2 servers.
Provides in-game commands, player stat tracking and ranking, live MOTD
scoreboard and stats, greeter, and admin functions. Running entirely through
the web admin, it does not affect a server's ranked/custom status. It can be
ran either directly on the server or remotely, and manage multiple servers at
once.
Downloads
---------
The most recent stable version is `0.1.6`. A binary is provided on the releases page for Windows and Linux users.
[Release 0.1.6](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.6)
Old releases
* [Release 0.1.5](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.5)
* [Release 0.1.4](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.4)
* [Release 0.1.3](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.3)
* [Release 0.1.2](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.1.2)
* [Release 0.0.7](https://github.com/th3-z/kf-magicked-admin/releases/tag/0.0.7)
Features
--------
### Commands
When inputting commands into the chat they need to be prefixed with `!`.
When writting commands into a script, or chaining them this should be
omitted.
Many commands will look for closest matches to their parameters.
For example '_biotics_' will match '_kf-biotics-lab_' and '_userO_' will match
'_userOne™/@:®_'.
All commands have in-game help text that can be accessed with the `-h` flag.
* Example: `!commands -h`
All commands also have the following flags.
* `-q` - Suppresses output
* `-p` - Pads output to hide the username line
Escape sequences as follows are available to format messages.
* `\n` - Newline
- Example: `!say line 0\nline 1`
* `\t` - Tab
- Example: `!say line 0\n\tline 1 is indented`
#### Player commands
Commands that can be executed by any player.
Click to see the player commands!
* `!commands` - Shows a list of all commands available to players
* `!stats ` - Shows general statistics about a user
- Example: `!stats` Shows stats about yourself
- Example: `!stats the_z` Shows stats about the_z
* `!kills ` - Shows kill statistics about a user
- Example: `!kills` Shows kill stats about yourself
- Example: `!kills the_z` Shows kill stats about the_z
* `!dosh ` - Shows dosh statistics about a user
- Example: `!dosh` Shows dosh stats about yourself
- Example: `!dosh the_z` Shows dosh stats about the_z
* `!time ` - Shows time statistics about a user
- Example: `!dosh` Shows time stats about yourself
- Example: `!dosh the_z` Shows time stats about the_z
* `!map` - Shows statistics about the current map
* `!record_wave` - Shows the highest wave achieved on the current map
* `!top_kills` - Shows the global kills leaderboard
* `!top_dosh` - Shows the global dosh leaderboard
* `!top_time` - Shows the global play time leaderboard
* `!top_wave_kills` - Shows information about who killed the most ZEDs
in the current wave. Generally for use with `start_trc`
- Example: `!start_trc -- top_wave_kills`
* `!top_wave_dosh` - Shwows information about who earned the most dosh in
the current wave. Generally for use with `!start_trc`
- Example: `!start_trc -- top_wave_dosh`
* `!server_kills` - Shows total kills on the server
* `!server_dosh` - Shows total dosh earned on the server
* `!scoreboard` - Shows the complete player scoreboard, useful on servers with >6 max players
- Alias: `!sb` Does the same
* `!game` - Shows information about the current game
* `!maps [--all]` - Shows the current map cycle
- Option `-a`: Show all available maps
* `!player_count` - Shows the player count and max players
#### Admin commands
Commands that can be ran by server administrators or users authorized with
the `!op` command.
Click to see the admin commands!
* `!op ` - Gives a user administrative rights
- Example: `!op the_z`
* `!deop ` - Revokes a user's administrative rights
- Example: `!deop the_z`
* `!say ` - Echoes a message into chat
- Example: `!say The quick brown fox jumps over the lazy dog`
- Example: `!start_trc -- say The trader is open`
* `!players` - Shows detailed information about players on the server
* `!kick ` - Kicks `` from the match
- Example: `!kick the_z`
* `!ban ` - Bans `` from the server
- Example: `!ban the_z`
- Warnng: The web admin currently has a bug that causes bans to persist
after they are deleted, thus there is no unban command
* `!length ` - Change the length to `` next game
- Example: `!length short`
* `!difficulty ` - Change the difficulty to `` next
game
- Example: `!difficulty hell`
* `!game_mode ` - Immediately change the game mode to ``
- Example: `!game_mode endless` Changes the game mode to Endless
* `!load_map ` - Immediately change the map to ``
- Example: `!load_map biotics` Changes the map to Biotics Lab
* `!restart` - Immediately restart the current game
* `!password [--set] `
- Example: `!password on` Enables the game password defined in the config
- Example: `!password off` Disables the game password
- Example: `!password --set somePass` Sets a specific password
* `!start_jc [-r] -- ` - Start a command that runs every time a player joins
- `-r` Only run for returning players
- Example: `!start_jc -- say Welcome %PLR` - Greets a player on join
- Available tokens: `%PLR` - username, `%KLL` - total kills, `%DSH` -
total dosh; `%PLR` - username, `%BCK` - "back" if sessions > 1, `%DRK` -
dosh rank, `%KRK` - kill rank, `%TME` - play time, `%TRK` - play time
rank, `%SES` - sessions
* `!stop_jc` - Stops all join commands
* `!start_wc [-w ] -- ` - Start a command that runs on wave ``
- `-w` Wave to run the command on, can be omitted to have the command
run every wave
- `-w` Can be negative to count backwards from the boss wave
- Example: `!start_wc -1 -- say Welcome to the boss wave`
* `!stop_wc` - Stops all wave commands
* `!start_tc [-r, -t ] -- ` - Start a command that runs after
`` seconds
- Option `-r`: Add to have the command run repeatedly
- Option `-t`: Required, the number of seconds before the command runs
- Example: `!start_tc -rt 600 -- say Join our Steam group!\n
http://steam.group/`
* `!stop_tc` - Stops all timed commands
* `!start_trc [-w ] -- ` - Start a commands that runs when the trader opens
- `-w` Wave to run the command on, can be omitted to have the command
run every wave
- `-w` Can be negative to count backwards from the boss wave
- Example: `!start_trc -- top_wave_dosh` - Shows who earned the most dosh
every wave when the trader opens
* `!stop_trc` - Stop all commands that run on trader open
* `!silent` - Toggles suppression of all chat output, commands still have
effect, but the response will not be visible to players
* `!run ` - Executes a script from the `conf/scripts` folder, more
information in the scripts section
- Example: `!run example`
* `!marquee ` - Runs a marquee in the chat from the
`conf/marquee` folder, _experimental_
- Example: `!marquee example`
* `!update_motd ` - Refreshes the welcome screen leaderboard, type is
one of: kills, dosh, or time
- Example: `!start_tc 300 -- update_motd kills`
* `!reload_motd` - Reloads the server's `*.motd` file from `conf`
* `!alias` - Check the help text `!alias -h`
* `!enforce_dosh ` - Kicks all players that have more dosh than the specified `amount`
- Example: `!start_tc 600 -- enforce_dosh 60000`
### MOTD leaderboard
A sample `.motd` file is provided in `conf/`. The filename should match the server's name as
specified in `conf/magicked_admin.conf`. The template format is Jinja2. An example follows,
please refer to the [Jinja2 designer documentation](https://jinja.palletsprojects.com/en/2.11.x/templates/).
```
Welcome to our server.
{{ millify(server_kills) }} Zeds killed on this server.
Top Players (total dosh):
{% for player in top_dosh[0:9] -%}
{{loop.index}}. {{player.username|truncate(11)}} [{{millify(player.score)}}] {% if loop.index is divisibleby 3 %}
{% endif %}
{%- endfor %}
Have fun and good luck!
```
### Scripts
Writing a `server_name.init` in the `conf/scripts` folder with a series of commands
will run the commands in sequence when the bot starts on `server_name`.
Additional scripts can be written in the `conf/scripts` folder and ran with the
`!run` command. There is an example already in there that can be ran with
`!run example`.
* Comments can be added to scripts by prefixing a line with `;`.
### Webadmin patches
For gamemodes other than survival to function in full patches have to be
applied to the `KFGame/Web/ServerAdmin` folder on the server. For this reason
a script is provided in the `admin-patches` folder that will automatically
patch your server.
There is currently no CLI or Windows build for this component. You can run it
with `python3 admin-patches/admin-patches.py`. A dialogue box will appear
asking you to locate your server.
Configuration options
---------------------
Basic setup is done on the first run. However this does not cover all of the
options KF2-MA can offer. Please see the config file, `conf/magicked_admin.conf`,
for more configuration options as some features are disabled by default.
Each server managed by KF2-MA has a section that looks something like
`[server_one]`, followed by several options (`x = y`). Copy and edit the
default server section if you want to manage multiple servers. `[server_one]`
is the name of the server, this can be changed to whatever you want.
### Options
Options can be configured in the config file `conf/magicked_admin.conf`.
* `address`
- Web address of the server's webadmin panel. Requires scheme and protocol,
e.g. `https://0.0.0.0:8080`
* `username`
- Webadmin username to login with, this will appear in the chat when the
bot has something to output. It's recommended to create a separate account
for the bot.
* `password`
- Webadmin password that matches the username above.
* `game_password`
- Default game password to set when the password is toggled using
`!password `.
* `refresh_rate`
- Integer value, webadmin polling rate
Running with Docker
---------------------------
Running with docker is easy. Just issue this command:
```
docker run -it -p 1880:1880 --name kf2-magicked-admin -v '':'/magicked_admin/conf' th3z/kf2-magicked-admin
```
You will need to change `` to wherever you want
to store your config folder. `/mnt/user/appdata/kf2-magicked-admin` is a popular
choice for systems running Unraid.
After this command runs the container will exit out and the logs will tell you
to setup the config file. Go to your `conf` folder and set things up then run
the container again and you are good to go!
If 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:
```
docker run -it -p 1880:1880 --name kf2-magicked-admin -v '':'/magicked_admin/conf' -v '':/kf2-server -v '':/kf2-server-two -e 'PATCHES_TARGET_DIR'='/kf2-server,/kf2-server-two' th3z/kf2-magicked-admin
```
Running from Python sources
---------------------------
Before contributing code you will need to install the Python requirements.
### Requirements
Examples work on Debian 10 and Ubuntu Xenial, may differ for other operating
systems. Install the following packages.
* Python 3.7 - `apt install python3`
* Pip - `apt install python3-pip`
* Pybabel - `apt install python3-babel`
* Python 3 dependencies - `pip3 install -r requirements.txt`
- This might complain about cx\_freeze not installing if you haven't got
zlib-dev, but cx_freeze is only needed for building.
### Running
`git clone https://github.com/th3-z/kf2-magicked-admin.git`
`cd kf2-magicked-admin`
`pip3 install -r requirements.txt`
`make i18n-compile`
`python3 -O magicked_admin/magicked_admin.py`
The `-O` flag runs the program in release mode, remove it to run KF2-MA in
debug mode. Debug mode will enable more detailed output.
Building
--------
You can build a binary release for distribution with `make` after installing
both the run and build requirements.
### Requirements
Examples work on Debian 10 and Ubuntu Xenial, may differ for other operating
systems.
* Python 3.7 - `apt install python3`
* Pybabel - `apt install python3-babel`
* Pip - `apt install python3-pip`
* Pip dependencies - `pip3 install -r requirements.txt`
* Make - `apt install make`
On Windows it's recommend to build with Cygwin. However you can also build it
by running `python3 setup.py build`. Check the makefile for help building the locale files.