Project Zomboid Discord Bot for Server Management

This bot is written for people to easily manage their Project Zomboid server using Discord. Please check the Installation and Bot Configuration section. Also this bot doesn't support multiple discord servers and only works on Windows operating system. Be sure to have .NET Framework 4.7.2 installed on the machine.

Contents

• Features
• Installation
  • Creating the Discord Bot
  • Installing Bot Files
  • Writing the Discord Bot Token Into File
• Bot Configuration
• Bot Commands
  • Public Channel
  • Command Channel
• Localization

Features

• Automated server restart schedule with ingame and discord warning. (Warnings are announced when 1 hour, 30 min, 15 min, 5 min and 1 min left until server restart. Restart interval can be configured with bot commands.)
• Automated server restart when a mod (workshop item) update has been detected.
• Executing server commands through bot commands. (For example; saving server, kicking player, teleporting player, starting/stopping rain, making admin and so on. Full list will be at the bottom and will be listed under available commands.)
• Perk Parser with cache system. (Bot automatically parses the last perk log file that holds the player skills when they login to server. This can be used to aid players that died to a bug but they can't remember their skills. As stated before, server logs the player skills only when they log into server. If player levels up a skill after connecting to server, it won't appear in log unless player logs into server afterwards again.) When command for perk parser is invoked, bot will parse the file and save it contents in memory until cache (in minutes) expires. This is for to increase efficiency as bot will not have to parse the same file each time. In a situation where fresh data needed, !reset_perk_cache command can be used to reset the cache.
  
• Auto server start if server quits. This feature useful if combined with mods that quits the server for whatever reason. For example, if you are using a mod that checks mod updates and when detects it, quits the server. With enabling this feature, you won't need to manually run the server.
  
• !get_ram_cpu command for checking current RAM and CPU usage of the machine.
• !backup_server command for backing up the server easily.
• Localization system! You can check available localizations using !localization command. See the Localization section about how to translate the bot. Note: It is not possible to translate commands and their descriptions at the moment. It might change in future, though.

Installation

Creating the Discord Bot

1. Go to Applications section of Discord developer portal. (Be sure to login first.)
2. Click to New Application button on the top right corner of screen.
3. Enter your Bot's name in pop-up then click to create button. You will be redirected to your application's (bot's) page. In that page, you can update your bot's name, description and even load an image as avatar.
4. Navigate to Bot section from left menu. Then click to Add Bot button. Then confirm the pop-up. You will be redirected to your bot page.
5. Click to Reset Token button. Then confirm the pop-up. This will create a new token for your bot. Copy the displayed token and save it in a file. You won't able to view your bot token unless you reset it again. Also do not share this token with anyone. It's basically password of your bot. If you share it with someone else, they will have full control on your bot.
6. Navigate to OAuth2 section from left menu and select the URL generator from dropdown. Check bot from Scopes section and scroll down to Bot Permissions.
7. Check the options shown below and copy the generated URL.
8. Open the copied link on your browser. In the page, select the server (you must be admin on the server otherwise server won't show up but you can always send the link to an admin which they can authorise the bot) that you want bot to work in. Click to Continue button and then to Authorise button. Complete the captcha if it pops-up. Now Bot has joined to your server but it's not running yet.
   

Installing Bot Files

To complete this step and next step, you must have remote access to your Windows machine.

1. Navigate to releases and pick a binary version. I would suggest picking the latest version as it would consist new features and bug fixes.
2. Download the zip archive.
3. Extract the contents in the archive to the Project Zomboid Dedicated Server folder. Your directory after extraction will look like the image below.
   
4. Rename the bat file you were using to start the server as server.bat. For example, if you were using StartServer64.bat, rename it as server.bat.

Writing the Discord Bot Token Into File

1. Create an empty text file in the directory and name it as bot_token.txt and open it.
2. Paste the bot token that you saved while creating the discord bot to the first line. (It will look like the picture below.)
3. Save the file and close it.

Now all you need to do is running PZServerDiscordBot.exe. If you did setup everything correctly, program will automatically run the Discord bot at background and will show the Project Zomboid Server in the console. (Bot may not send the warning messages about the configuration if your discord server's last created channel is not accessable by the bot. You can just type configuration commands regardless.)

Note:
If you never run the project zomboid server before, please run it without using bot. Because when you run the project zomboid server for the first time, it will ask you to setup an admin account. You can't send any key presses to console if you run the server through discord bot's exe file. This also means you can't execute servers commands directly using the console but I did setup all commands in discord bot.

Warning:
If bot doesn't respond to any commands, that could be mean two things:

• Bot doesn't have permission to see the channel. Be sure that bot has full access on the channel which also includes permission to send messages. After confirming bot has full access but still won't respond, see below.
• Bot has missing intents configuration. Please head to discord developer portal (which is the place you did create and set up your bot), select your bot, click to the Bot tab on left menu and be sure that all bot intentions are enabled under the Privileged Gateway Intents section.

Bot Configuration

This bot uses 3 different channels to operate. First channel is Public channel where users can interact with bot. Second channel is Command channel where must set to be only visible to server admins. This channel is used for executing server management and bot configuration commands. Third channel is Log channel. There aren't any commands to execute in this channel and it's set for bot to announce stuff. After the bot launched for first time (or not configured), it will ask you to configure the mentioned three channels using !set_command_channel, !set_log_channel and !set_public_channel commands. Those commands are very easy to use. Just reply to any channel with the tag of the channel you want the bot to be configured in. For example: !set_public_channel #bot-public

Bot Commands

!help command can be used in any of configured 3 channels which bot will respond with the available command list for that channel.

Public Channel

• !bot_info Displays information about this bot. (!bot_info)
• !server_status Gets the server status. (!server_status)
• !restart_time Gets the next automated restart time. (!restart_time)
• !game_date Gets the current in-game date. (!game_date)

Command Channel

Bot Commands:

• !set_command_channel Sets the channel for bot to work in. (!set_command_channel [channel tag>)
  
• !set_log_channel Sets the channel for bot to work in. (!set_log_channel [channel tag])
  
• !set_public_channel Sets the channel for bot to work in. (!set_public_channel [channel tag])
  
• !get_settings Gets the bot settings. (!get_settings)
  
• !get_schedules Gets the remaining times until schedules to be executed. (!get_schedules)
  
• !get_ram_cpu Gets the total RAM and CPU usage of the machine. (!get_ram_cpu)
  
• !set_restart_schedule_type Set the server's restart schedule type. (!set_restart_schedule_type ["interval"|"time"])
  
• !set_restart_time Set the server's restart time(s). The time format is "HH:mm" (using 24-hour time). Server restart schedule type must be "time". (!set_restart_time [times separated by space])
  
• !set_restart_interval Set the server's restart schedule interval. Restart schedule type must be "interval". (in minutes!) (!set_restart_interval [interval in minutes])
  
• !set_mod_update_check_interval Set the workshop mod update check schedule interval. (in minutes!) (!set_mod_update_check_interval [interval in minutes])
  
• !set_mod_update_restart_timer Sets the restart timer for server when mod update detected. (in minutes!) (!set_mod_update_restart_timer [timer in minutes])
  
• !toggle_non_public_mod_logging Bot will print out non-public mods to log channel if enabled. (!toggle_non_public_mod_logging)
  
• !set_perk_cache_duration Set the perk cache duration. (in minutes!) (!set_perk_cache_duration [duration in minutes])
  
• !reset_perk_cache Reset the perk cache. (!reset_perk_cache)
  
• !toggle_server_auto_start Enables/Disables the server auto start feature if server is not running. (!toggle_server_auto_start)
  
• !backup_server Creates a backup of the server. Backup files can be found in "server_backup" folder in the directory where bot has been launched. (!backup_server)
  
• !localization Get/change current localization. (!localization [(optional) new localization name])
  

Server Commands:

• !server_cmd Allows you to send inputs to the server console. (!server_cmd [text])
  
• !server_msg Broadcasts a message to all players in the server. (!server_msg "[message]")
  
• !start_server Starts the server. (!start_server)
  
• !stop_server Saves and stops the server. (!stop_server)
  
• !restart_server Restarts the server. (!restart_server)
  
• !initiate_restart Initiates a restart. (!initiate_restart [minutes until restart])
  
• !abort_restart Aborts an upcoming restart. Works both with restart schedule and manual initiated restart. (!abort_restart)
  
• !save_server Saves the current world. (!save_server)
  
• !perk_info Displays the perk information of player. (!perk_info "[username]")
  
• !add_user Adds a new user to the whitelist. (!add_user "[username]" "[password]")
  
• !add_user_to_whitelist Adds a single user connected with a password to the whitelist. (!add_user_to_whitelist "[username]")
  
• !remove_user_from_white_list Removes a single user connected with a password to the whitelist. (!remove_user_from_whitelist "[username]")
  
• !ban_steamid Bans a Steam ID. (!ban_steamid [steam id])
  
• !unban_steamid Unbans a Steam ID. (!unban_steamid [steam id])
  
• !ban_user Bans a user. (!ban_user "[username]")
  
• !unban_user Unbans a user. (!unbanuser "[username]")
  
• !make_admin Gives admin rights to a user. (!make_admin "[username]")
  
• !remove_admin Removes admin rights to a user. (!remove_admin "[username]")
  
• !kick_user Kicks a user from the server. (!kick_user "[username]")
  
• !start_rain Starts rain on the server. (!startrain)
  
• !stop_rain Stops rain on the server. (!stoprain)
  
• !teleport Teleports a player. (!teleport "[username1]" "[username2]") | Username 1 will be teleported to Username 2.
  
• !add_item Gives an item to the player. (!add_item "[username]" "[module.item]")
  
• !add_xp Gives XP to a player. (!addxp "[username]" "[perk]" [xp])
  
• !chopper Places a helicopter event on a random player. (!chopper)
  
• !godmode Makes a player invincible. (!godmode "[username]")
  
• !invisible Makes a player invisible to zombies. (!invisible "[username]")
  
• !noclip Allows a player to pass through solid objects. (!noclip "[username]")
  
• !show_options Shows a list of current server options and values. (Prints to the server console) (!show_options)
  
• !reload_options Reloads server options. (!reload_options)
  
• !change_option Changes a server option. (!change_option "[option]" "[newOption]")
  
• !add_workshop_mod Adds a workshop mod from the workshop mod url. (!add_workshop_mod [workshop mod urls with spaces in-between])
  
• !remove_workshop_mod Removes a workshop mod from the workshop mod url. (!remove_workshop_mod [workshop mod urls with spaces in-between])
  

Localization

You can find the default localization file in here. All you need to do is downloading it and translating the all words/sentences in the right side of ":" between two quote marks. Example below will illustrate how it should look like after the translation.

Before translation:

{
  "gen_enab_up": "Enabled",
  "gen_disa_up": "Disabled",
  "gen_hours_text": "hour(s)",
  ...
  "warn_server_not_running": "Server is not running.",
  "warn_bot_conf_not_done": "Bot configuration haven't done yet.",
  ...
}

After translation:

{
  "gen_enab_up": "Aktif",
  "gen_disa_up": "Pasif",
  "gen_hours_text": "saat",
  ...
  "warn_server_not_running": "Server çalışmıyor.",
  "warn_bot_conf_not_done": "Bot ayarları henüz tamamlanmadı.",
  ...
}

Warning: There might be cases where you can see some weird expressions like {log_file}, {current_version}, {state} etc. These are special expressions that will be replaced with related value before displaying the text. Do not translate these. However, you can move them freely in a sentence and match them with your own language's sentence structure.

Some examples of how some of the expressions will look like after the related value replacement:

{day}/{month}/{year} -> 19/12/2022
{year}-{month}-{day} -> 2022-12-19

Bot Version: {version}  -> Bot Version: v1.8.0
Bot Version ({version}) -> Bot Version (v1.8.0)

Server auto start feature has been {state}.      -> Server auto start feature has been enabled.
Non-public mod logging feature has been {state}. -> Non-public mod logging feature has been disabled.

{hours} hours ago -> 10 hours ago
hours ago {hours} -> hours ago 10

After you have completed translating all words/sentences, please create an issue by selecting the Localization Submission template with the title of Localization of <language here> and attaching the translated .json file in a zip archive. I will add it to available localizations. Also, when a new version of the bot released, there might be new added text so it is good to keep an eye on updates. If your current localization is missing the new added text, bot will use the default localization for these.