Kinematica

The Swiss Army Knife of Discord Bots

Overview

Kinematica (/kɪnəˈmætɪkə/) is a multifunctional Discord bot designed to enhance your server experience with a variety of features. Whether you're looking for entertainment, utility, or moderation tools, Kinematica has you covered. With a focus on user engagement and server management, Kinematica offers a range of commands and functionalities to suit your needs. Kinematica aims to be the Swiss Army Knife of Discord bots, providing a comprehensive set of tools in one package. From music playback to group film nights, Kinematica is built to make your Discord server more dynamic and enjoyable.

Getting Started

Prerequisites

• Python 3.12.0 or higher
• pip 24.0.0 or higher
• A PostgreSQL/MySQL/MariaDB/SQLite database, or another database supported by SQLAlchemy
• Lavalink (required for music commands)

Installation

1. Clone the repository

git clone https://github.com/kgdn/kinematica.git

2. Install the required packages

pip install -r requirements.txt

Configuration

Note

Before proceeding, you need to create a Discord bot, set up a database, and get a TMDB API key.

We'll assume you already have a Discord bot set up. If not, you can create one by following the instructions on the Discord Developer Portal.

You can use any database URI supported by SQLAlchemy. For more information, refer to the SQLAlchemy documentation. We recommend using SQLite for development and PostgreSQL or MySQL/MariaDB for production.

To use the music commands, you'll need to set up Lavalink. You can find the Lavalink website here.

You can get a TMDB API key by creating an account on the TMDB website.

Once you have the required information, you can proceed with the configuration.

1. Create a .env file in the root directory and add the following:

BOT_TOKEN=YOUR_BOT_TOKEN
DATABASE_URI=YOUR_DATABASE_URI
TMDB_API_KEY=YOUR_TMDB_API_KEY
VERSION=1.0.0
LAVALINK_URL=YOUR_LAVALINK_URL
LAVALINK_PASSWORD=youshallnotpass

Replace YOUR_BOT_TOKEN with your Discord bot token, and fill in the database and TMDB API key information.

4. Create the status.json inside the json directory. An example schema has been provided below.

{
  "playing": [
    "..."
  ],
  "watching": [
    "..."
  ],
  "listening": [
    "..."
  ],
  "streaming": [
    ["https://www.youtube.com/watch?v=dQw4w9WgXcQ", "A perfectly normal link"]
  ]
}

Starting the Bot

To run the bot, just run the following command:

python app.py

Docker

You can also run the bot using Docker. To do this, you need to pull the Docker image from Docker Hub or build the Docker image first. You should have ensured that you have created a .env file with the required environment variables. It is recommended that you use a PostgreSQL or MySQL/MariaDB database when running the bot in a Docker container.

To pull the Docker image from Docker Hub, run the following command:

docker pull kgdn/kinematica:latest

If you prefer to build the Docker image yourself, you can do so with the following command:

docker build -t kinematica .

Then, you can run the bot using the following command:

docker run -d --env-file .env -v $(pwd)/json:/app/json --name kinematica kgdn/kinematica:latest

Alternatively, you can use Docker Compose to run the bot. An example docker-compose.yml file has been provided in the repository. You can modify it to suit your needs. The example file uses PostgreSQL as the database.

To run the bot using Docker Compose, run the following command:

docker compose up -d

Contributing

Important

When contributing to Kinematica, please follow the PEP 8 style guide for Python code. Please ensure that your code follows the PEP 8 style guide and that your commit messages are clear and concise. Please use Ruff to format your code before committing.