Installation ¶

Discord-HvZ is a Python application that you run yourself on nearly whatever computer you like. There are both Windows and Linux versions available, with a Mac version coming soon.
You must complete all the steps on this page for the bot to launch without errors.

Info

While setting up and managing your bot, you will have to edit configuration files. It will be more pleasant to edit these with a text editor that understands code, such as Notepad++.

Software Installation¶

There are two ways to install the software itself:

Express Install

Download a simple executable that runs from a folder.

This is an easy method for those who don't care about viewing or editing the source code. The caveat is that you can't use custom script processors, which is an advanced feature that doesn't have documentation yet.

Advanced Install

Install the Python package with all dependencies.

This allows one to edit any of the source code, and use custom script processors. For those who intend to tinker with things under the hood, or even contribute to the project.

This install is a more involved process where more things can go wrong. If using Windows, it may even require a 6GB download.

Swapping Between Install Methods

If you've been using the program with one install method and want to swap, simply move the critical files between them. You can't transfer custom script processors to an Express Install.
These are the files you should transfer, if they exist:

.env
config.yml
credentials.json
hvzdb.db
scripts.yml
token.json

Express Install¶

Windows Linux

Download the latest "Express Install" .zip for Windows from Releases
Unzip it to a convenient folder you intend to run the bot from.
Run Discord-HvZ.exe. The app should open, then close with an error because there are still setup steps to complete. Start with Creating a Discord Bot

Alternate Start Method

If you'd like the terminal window to stay open between runs of the bot so you can read errors easier, you'll have to start it from a terminal.
In File Explorer, go inside the install folder, click once in the address bar, type cmd or powershell, then hit Enter.
Now type .\Discord-HvZ.exe and hit Enter. The bot will start. Use Ctrl + C to force shutdown the bot. Use the Up arrow key and Enter to restart it.

Download the latest "Express Install" .zip for Linux from Releases
Unzip it to a convenient folder you intend to run the bot from.
Run Discord-HvZ through a command window. (Otherwise, the program runs without a window, which is a Linux problem.) The app should open, then close with an error because there are still setup steps to complete. Start with Creating a Discord Bot

Advanced Install¶

Advanced Install Instructions

Windows Linux

These instructions assume you have already installed Python programs before.

Download an "Source code" .zip for Windows from Releases OR download the project directly from the branch you want. Unzip it to a convenient folder you intend to run the bot from.
Install any Python version from 3.9.7 to 3.10.x. If helping with development, use 3.9.x. Open a command prompt and use python --version to see what you already have installed, if anything.
The below steps are how to install the project's dependencies from a pyproject.toml file with Poetry. There are other ways to do this which you are welcome to try.
Unfortunately, to compile C code that's a part of many Python modules, you need this ~6 GB software from Microsoft. Download the Build Tools for Visual Studio Installer. Launch it, select Desktop Development, then install the minimum items as shown:
To install Poetry without polluting your system with its dependencies, use the following commands in your command prompt to install pipx for your user account. The second command lets you use the pipx module directly from the command prompt.
```
python -m pip install --user pipx
python -m pipx ensurepath
```
Use the following to install Poetry in its own isolated space on your system.
```
pipx install poetry
pipx ensurepath
```
Direct your command prompt to your Discord-HvZ folder.
(Pro tip: You can do this by clicking once in the address bar of File Explorer, typing cmd or powershell, then hitting Enter.)
Do you want to install Discord-HvZ with a Python version other than the one currently active? Use the command here.
Install the dependencies for Discord-HvZ in a virtual environment for this specific folder:
```
poetry install
```
If you're assisting with development, use this instead:
```
poetry install --with dev
```
Create a file in the install directory called .env and open it in a text editor. Put TOKEN='' inside. You will fill the quotes with a Discord token in a later step.
Run the bot:
```
poetry run main
```
The bot should run, then close with an error because there are still setup steps to complete. Keep reading below!

These instructions assume you have already installed Python programs before and are familiar with Linux.
(I am not very familiar with Linux.)

Download an "Source code" .zip for Linux from Releases OR download the project directly from the branch you want. Unzip it to a convenient folder you intend to run the bot from.
Linux often comes with Python installed. Open a command prompt and use python3 --version to see what you already have installed. You may use any Python version from 3.9.7 to 3.10.x. If helping with development, use 3.9.x. (Installing alternate Python versions on Linux is baffling to me. Good luck!)
The below steps are how to install the project's dependencies from a pyproject.toml file with Poetry. There are other ways to do this which you are welcome to try.
To install Poetry without polluting your system with its dependencies, use the following commands in your command prompt to install pipx. The second command lets you use the pipx module directly from the command prompt.
```
sudo apt update
sudo apt install pipx
```
Use the following to install Poetry in its own isolated space on your system.
```
pipx install poetry
pipx ensurepath
```
Restart your command prompt and direct it to your Discord-HvZ folder.
Do you want to install Discord-HvZ with a Python version other than the one currently active? Use the command here.
Install the dependencies for Discord-HvZ in a virtual environement for this specific folder:
```
poetry install
```
If you're assisting with development, use this instead:
```
poetry install --with dev
```
Create a file in the install directory called .env and open it in a text editor. Put TOKEN='' inside. You will fill the quotes with a Discord token in a later step.
Run the bot, with your command prompt directed to the project folder:
```
poetry run main
```
The bot should run, then close with an error because there are still setup steps to complete. Keep reading below!

Creating a Discord Bot¶

Setting Up a Bot Account¶

Go to the Discord Developer Portal and login with your account.
Go to the Applications page and create a new application. The name you select here is not the name of the bot. This "application" is more like a set of credentials that the bot will use.
Go to the Bot tab of your new Application and click Add Bot. Give it the username it will have on your server. Make sure the Public Bot switch is off. This bot should be private.
Turn on all Privileged Gateway Intents.
Use the Copy button on this page to copy the bot token to your clipboard. This is a secret code that lets your bot identify itself to Discord. If someone else gets this token, they can impersonate your bot: never share it.
Go to your installation of Discord-HvZ and open the .env file in a text editor. Your OS may hide files that start with a ., so you may need to show hidden items through the View menu of your file browser.
Paste your token between the quotes and save the file. The file should then look something like this: TOKEN='123ABC789a456g6_ad45.816d_d454wd' Your bot now has permission to use the account Discord gives it.

Inviting the Bot¶

Make sure you have the administrator access on the Discord server you want to run the bot on. You need to be able to invite the bot and manage its permissions.
Go back to the application you created on the Discord Developer Portal and to the URL Generator page in the OAuth2 section.
Check boxes until the permissions look like the picture below. These are the permissions your server needs to grant the bot to do its job.
Copy the Generated URL and use your browser to follow it. Follow the instructions to invite your bot to the correct server.
If on desktop, go to Discord and turn on Developer Mode in the Advanced settings menu. Right click your server's icon and Copy ID to get the server ID. If using the browser version of Discord, go to your server, then copy the first long number in the address bar.
Open the config.yml file in your installation of Discord-HvZ and find the server_id setting, replacing that ID with that of your server. Now your bot knows which server it should interact with. Note that the bot is not designed to work on multiple servers at once.

Setting up Google Sheets¶

The nicest way the bot displays the player and tag lists is through a Google Sheets document. Anyone who knows how to use a spreadsheet can read and manipulate the information. Unfortunately, Google makes their interface to set this up a bit awkward. Feel free to come back to this step later by disabling the Sheets feature by setting the google_sheets_export option in config.yml to false.

The interfaces on the following Google pages are big and complicated. Take your time and look carefully.

Go here to make a Google Cloud Platform project. The Location field is not important.
Use the navigation menu in the top left and go to APIs & Services then Library. Search for "Google Sheets" and Enable the Google Sheets API.
Go back to APIs & Services, but this time to the OAuth consent screen page. Follow the instructions there to set up a consent screen, only filling in the required information and skipping everything else.
Go to the Credentials tab of the APIs & Services section and use the Create Credentials button to make an OAuth client ID. Again, the information you put in here isn't critical.
When done, you'll get the option to DOWNLOAD JSON. Look around for a icon and download the file to your installation of Discord-HvZ.
Rename this .json file to credentials.JSON. Now your bot has permission to communicate with Google!
Go to Google Drive and create a Sheets document which will be used to display members and tags to your admin or moderator team during the game. Set up its location and permissions appropriately for that purpose.
Add two sheets to this document: one called "Members" and the other called "Tags". If you want to change these names, see the sheet_names config option.
Copy the sheet ID from the URL in your address bar. It is the code highlighted here:
In config.yml, find the sheet_id setting and replace the ID there with yours. Now your bot knows what sheet to send data to.
The first time you launch the bot, it will open a browser window and ask you to log in with a Google Account. The only requirements for this account are that it has edit access to the bot's Google Sheet: it could be a personal account, or one created only for this purpose.

Bug

The Google login for Sheets will expire after a few days, even when running. That isn't supposed to happen unless the bot is offline for days.
Until this bug is fixed, reboot the bot daily to stay logged in.

Final Steps¶

Configure the channel_names section in config.yml. Please see Config Options: channel_names for information. You can change these channels later, but the bot must have permission to view and post in these channels.

Configure the roles section configured as well. See Config Options: role_names for information. The bot must have permission to manage these roles, meaning they have to be lower than it in the role hierarchy in the server settings.

Set the timezone the game is taking place in for the timezone setting.

Start the Bot¶

Now the time has come to start the bot for real, as described at the end of your chosen install method above. After you do, check if it spits out any alarming errors. If so, scroll up and check that you did everything.

There's still more to do before starting a game of HvZ, so continue to Server Setup.

Updating¶

To update the bot to a new version, follow the instructions for your installation method below.

Express Install

Backup your installation in case something goes wrong.
Download the Express Install .zip from Releases and unzip it somewhere. Copy the .exe file from there to your existing installation, overwriting.
Read the changelog for the version you want in Releases and any between it and your current version. In the Breaking Changes sections, read the notes. This will tell you if you need to change any other files before starting your bot. For example, if there was a breaking change to config.yml, you'll need to either fix yours, or add your information to the new file.

Advanced Install

Backup your installation in case something goes wrong.
Download the source code .zip from Releases and unzip it somewhere. Copy the following files from the original install to the new one:
- .env
- config.yml
- credentials.json
- [your_database_name].db
- scripts.yml
- token.json
- any other file you've customized
Read the changelog for the version you want in Releases and any between it and your current version. In the Breaking Changes sections, read the notes. This will tell you if you need to change any other files before starting your bot. For example, if there was a breaking change to config.yml, you'll need to either fix yours, or add your information to the new file.