The latest version as of writing is '0.1.5', released on the 25th of October 2019. A Windows executable is provided for this release here[github.com].

For Linux and Mac OS it is recommended to run the program from Python sources since you likely already have it installed. The source for '0.1.5' is available here[github.com]. You just need to install the requirements with 'pip3 install -r requirements.txt' and run it with 'python3 -O magicked_admin/magicked_admin.py'.

Development versions and build instructions are available on GitHub here[github.com].

Note: If you want to use Magicked Admin on an endless or weekly mode server there is an extra step that you have to do which I talk about in the "Endless and weekly game mode support" section.

1. Extract 'kf2-magicked-admin-0.1.5.zip' anywhere you like.
   
   
2. Double click the executable file
   
   
3. You will be guided through the first time setup
   
   Note: If you want to re-run the first time setup, just delete the file 'conf/magicked_admin.conf'

A Docker image is also available. Running with docker is easy, just issue the following command.

You will need to change '<host config folder location>' 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!

In the following sections I will describe all the commands. However there are some general things to note that apply to them all.

When inputting commands into the chat they need to be prefixed with '!'. When writing commands into a script, or chaining them the '!' 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.

• Option '-q': Suppresses output
  
• Option '-p': Pads output to hide the username line

Escape sequences as follows are available to format messages.

• '\n' - Newline
  - Example: '!say line 0 \n line 1'
  
• '\t' - Tab
  - Example: '!say line 0 \n\t line 1 is indented 1 tabstop'

These commands can be executed by any player. As of writing there are 18 player commands available.

• '!commands' - Shows a list of all commands available to players
  
  
• '!stats <user>' - Shows general statistics about a user
  - Example: '!stats' Shows stats about yourself
  - Example: '!stats the_z' Shows stats about the_z
  
  
• '!kills <user>' - Shows kill statistics about a user
  - Example: '!kills' Shows kill stats about yourself
  - Example: '!kills the_z' Shows kill stats about the_z
  
  
• '!dosh <user>' - Shows dosh statistics about a user
  - Example: '!dosh' Shows dosh stats about yourself
  - Example: '!dosh the_z' Shows dosh 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' - Shows 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' - Shows the current map cycle
  - Option '-a': Shows all available maps
  - Example: '!maps -a'
  
  
• '!player_count' - Shows the player count and max players

Commands that can be ran by server administrators, and users authorized with the '!op' command. As of writing there are 24 administrator commands available.

• '!op <user>' - Gives a user administrative rights, persists until '!deop <user>' is used.
  - Example: '!op the_z'
  
  
• '!deop <user>' - Revokes a user's administrative rights
  - Example: '!deop the_z'
  
  
• '!say <message>' - 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 <user>' - Kicks '<user>' from the match
  - Example: '!kick the_z'
  
  
• '!ban <user>' - Bans '<user>' from the server
  - Example: '!ban the_z'
  - Warning: The web admin currently has a bug that causes bans to persist after they are deleted, thus there is no unban command
  
  
• '!length <length>' - Change the length to '<length>' next game
  - Example: '!length short'
  
  
• '!difficulty <difficulty>' - Change the difficulty to '<difficulty>' next game
  - Example: '!difficulty hell'
  
  
• '!game_mode <game_mode>' - Immediately change the game mode to '<game_mode>'
  - Example: '!game_mode endless' Changes the game mode to Endless
  
  
• '!load_map <map>' - Immediately change the map to '<map>'
  - Example: '!load_map biotics' Changes the map to Biotics Lab
  
  
• '!restart' - Immediately restart the current game
  
  
• '!password [--set] <on|off>'
  - Example: '!password on' Enables the game password defined in the config
  - Example: '!password off' Disables the game password
  - Example: '!password --set superSekritPass' Sets a specific password
  
  
• '!start_jc -- <command>' - Start a command that runs every time a player joins
  - Example: '!start_jc -- say Welcome %PLR' - Greets a player on join
  - Available tokens: '%PLR' - username, '%KLL' - total kills, '%DSH' - total dosh, '%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 <wave>] -- <command>' - Start a command that runs on wave '<wave>'
  - Option '-w': Wave to run the command on, can be omitted to have the command
  run every wave
  - Option '-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 <seconds>] -- <command>' - Start a command that runs after
  '<seconds>' 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 <wave>] -- <command>' - Start a commands that runs when the trader opens
  - Option '-w': Wave to run the command on, can be omitted to have the command run every wave
  - Option '-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 <script_name>' - Executes a script from the 'conf/scripts' folder, more information in the scripts section
  - Example: '!run example'
  
  
• '!marquee <marquee_name>' - Runs a marquee in the chat from the 'conf/marquee' folder, experimental
  - Example: '!marquee example'
  
  
• '!enforce_dosh <amount>' - Kicks all players that have more dosh than the specified amount.
  - Example: '!start_tc 600 -- enforce_dosh 60000'
  
  
• '!update_motd <type>' - 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'

Writing a 'conf/server_name.motd' file containing pairs of '%PLR' and '%SCR' will allow you to render live leaderboard on the welcome screen.

A simple example could be as follows.

KF2 Magicked Admin will replace '%PLR' with the player's username, '%SCR' with the player's total kills or total dosh, '%SRV_K' with the global server kills, and '%SRV_D' with the global server dosh.

Once the file is written, use the '!update_motd <type>' command to refresh the leaderboard. This should be used in combination with '!start_tc <refresh_interval>' so that it is refreshed automatically.
- Example: '!start_tc 300 -- update_motd dosh'

The metric for '%SCR' can be either 'kills', 'time', or 'dosh'. This is can be set by changing the '<type>' parameter when using '!update_motd <type>'

Here is my survival suicidal welcome screen as an example of what can be achieved.

• This will overwrite your existing motd.
  
• '!reload_motd' Can be used to reload the template file while KF2 Magicked Admin is still running.

KF2 Magicked Admin has some rudimentary scripting support which can be used to chain commands into a single action.

There are two categories of scripts, they differ in when and how they are executed.

• Comments can be added to scripts by prefixing a line with ';'

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'. The server names are defined in 'conf/magicked_admin.conf', if you haven't changed the name it will default to 'server_one'.

An example init file will have been generated on first launch, this can be used as a template for writing your own init scripts.


The '!run' command exists to facilitate the running of scripts at any time. These scripts should be placed in the 'conf/scripts' folder. An example script is already in the scripts folder, it can be ran with '!run example'.

These scripts are formatted much the same as the init script, the commands will be ran in sequence from top to bottom.


Some commands are particularly useful when used in scripts, these are: '!start_tc', '!start_trc', '!start_wc', '!start_jc', '!top_wave_kills', '!top_wave_dosh', '!enforce_dosh', '!say'.

'conf/scripts/server_one.init' - Show who earned the most dosh each wave when the trader opens, and update the welcome screen leaderboard every 5 minutes

'conf/scripts/server_one.init' - Advertise your Steam group when the boss wave is reached

'conf/scripts/server_one.init' - Provide basic bot usage guidance to players

'conf/scripts/priv_game' - Setup a private lobby with a single command

'conf/scripts/greeter' - Starts a player greeter

Basic setup is done on the first run. However this is only to get you started, it does not cover all of the options KF2 Magicked Admin can offer. Please see the configuration file, 'conf/magicked_admin.conf', for more configuration options as some features are disabled by default.

Each server managed by KF2 Magicked Admin has a config section that looks something like '[server_one]', followed by several options ('x = y'). Copy the default server section and change the name if you want to manage multiple servers. '[server_one]' is the name of the server, this can be changed to whatever you want, but each section should have a unique name.


The following options can be configured in the config file 'conf/magicked_admin.conf'.

• 'address' - Web address of the server's web admin panel. Requires scheme and protocol
  - Example: 'address=https://0.0.0.0:8080'
  
  
• 'username' - Web admin 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.
  - Example: 'username=Admin'
  
  
• 'password' - Web admin password that matches the username above.
  - Example: 'password=123'
  
  
• 'game_password' - Default game password to set when the password is toggled using '!password <on|off>'.
  - Example: 'game_password=Hunter69'

To rename your chatbot to something other than 'Admin' your server must be configured for multi-admin.

If your server already has multi-admin support all you need to do is create an account with the desired name and change the account credentials in 'conf/magicked_admin.conf'

The following covers the same setup as the official Tripwire documentation on this topic, which is available here[wiki.killingfloor2.com].

1. Go to your server's config folder. 'KF2-Server\KFGame\Config\Config'.
   
   
2. Open 'KFWebAdmin.ini' in your favourite editor, add the following under the '[WebAdmin.WebAdmin]' section, and save the file.
   
   AuthenticationClass=WebAdmin.MultiWebAdminAuth
   
   
3. Now open your web admin panel and there should be a new 'Administrators' section in the sidebar.
   
   
   
4. Click 'Administrators' and select 'Create Administrator'. Enter a name for the Chatbot (This is the name you will use to sign in with). Click OK.
   
   
5. Give it a 'Display Name', 'Password', and enable the account (the display name is what players will see in chat).
   
   
   
6. Leave 'Access Order' set to 'Deny/Allow', and don't add any 'Deny Patterns' or 'Allow Patterns'. If you have issues using your new account, this is a common culprit so please leave it as is.
   
   
7. Click 'Save' and the account is ready for use.
   
   
8. Update the account credentials in 'conf/magicked_admin.conf'

In game modes other than survival KF2 Magicked Admin will have a limited feature set due to differences in the web admin panel when in other modes. However the web admin panel can be altered to enable the full feature set.

For this reason a web admin patcher is available here[github.com].

To use this utility your server files in 'KF2Server/KFGame/Web/ServerAdmin' will have to be stock/clean. If you have edited these files I suggest the following alternatives.

• Validate the server files with steamcmd with the command 'app_update 232130 validate' and use the patcher as normal.
  
• Manually apply the diffs in 'admin-patcher/patches' to your server files.

1. Run the executable
   
2. Open the location where your server is installed in the destination selection window
   
3. Click 'open'

• Run the executable with a target flag, e.g. './magicked_admin.exe --target /path/to/kf2/server'
  
• Check the console window for any issues

KF2 Magicked Admin can work with any amount of servers you run.

To configure more servers, find 'conf/magicked_admin.conf', and open it in your favourite editor.

Copy the whole '[server_one]' section, and paste it at the end of the file. Update the 'address', 'username', and 'password' options.

Below is an example.

You can do this for as many servers as you want.

If you have a few servers, you might want to name them so you can easily identify them.

You first need to open 'conf/magicked_admin.conf' and here you can change 'server_one' to anything you want.

You then need to go back and change 'server_one.motd' and 'server_one.init' to the name you just set it to in 'conf/magicked_admin.conf'.

To reset the scoreboard all you have to do is delete the 'conf/*.sqlite' file associated with the server name, a new one will be created the next time you start KF2 Magicked Admin.

If I wanted to reset the stats on 'server_four', I would delete the 'conf/server_four.sqlite' file and restart KF2 Magicked Admin.

The following features are currently slated for the next release.

• Command aliasing
  
• Lua scripting

There is an ongoing translation effort, if you know a language other than English you can contribute on Crowdin[crowdin.com].

We are accepting feature requests on the issue tracker[github.com].

• Issue with '!difficulty' and '!length' reliability. This is caused by an issue in the web admin panel, it will forget changes to these after certain other changes are made.
  - Workaround, use '!restart' immediately after them.

If you find a bug, please add it to the issue tracker[github.com]if you have a GitHub account.

If you don't have a GitHub account you can write it in the comments or message me on Steam.

KF2 Magicked Admin is open source software (MIT), authored by the_z (th3-z).
For full source code (Python+SQLite) and developer guidance visit the GitHub repository.[github.com]

Contributors

Developers:

• th3-z[github.com]
  
• n0x-io[github.com]
  
• skylord123[github.com]
  
• WilliamBrown42[github.com]

Testers:

• Stephen720
  
• WabbitToonz

Translators:

• W I [R] A - Spanish

Contributions are welcome.