Z3R0 (codename ziBot)

A free and open-source multi-purpose discord bot.

About

Development Stages

Nightly

->
Canary

->
Stable

Z3R0 (codename ziBot) is a free and open-source multi-purpose discord bot, was a fork of Steve-Bot by MCBE Speedrunning Moderators, created for fun in the middle of quarantine.

Features

• Custom Command: allow your mods or member to create a custom command,
  Custom command modes:
  • 0: Only mods can add and manage custom commands
  • 1: Member can add custom command but can only manage their own command
  • 2: Anarchy mode!
• Flags/Options: better specify your needs by using flags! (example: >command disable category: info will disable all command inside Information category)
• Fun commands: games, meme and other fun stuff.
• Powerful moderation command.
• Image manipulation/filters.
• Useful utility command such as execute (execute python/other programming language code), google, calc / math, and more!
• And more!

Usage

Quick Setup (Hosted)

Invite the officially hosted bot from this invite link.

For information on how to use the bot, see https://zibot.aap.my.id/docs

Self-Hosting

Warning

If you're planning to self-host the bot, I'll assume you already have a decent knowledge of Python, discord.py and hosting bot in general. I will NOT give support for basic issue such as "Where do I get bot token", "How to install Python", etc.

Hosting from free hosting such as Heroku is not supported either! It's recommended to get a proper VPS/Cloud Server to host a bot.

Docker

• Install Docker and Docker-Compose

• Create docker-compose.yaml file or use the one from docker/compose-examples:

  version: "3"
  
  services:
    bot:
      container_name: zibot
      image: ghcr.io/ziro-bot/z3r0:latest
      restart: on-failure
      volumes:
        - "./data:/app/data"
        - "./migrations:/app/migrations"
        - "./config.py:/app/config.py"

• Then run:

  docker-compose up -d
  
  # or if you want to use one of the sample yaml file
  docker-compose -f docker/compose-examples/basic/docker-compose.yml up -d

Since 3.5.0, ziBot support environment variables, added specifically for Docker

Env	Json	Description
ZIBOT_TOKEN	token	REQUIRED. Discord Bot's token, without it you can't run the bot at all. You can get it on https://discord.com/developers/applications
ZIBOT_DB_URL	sql	REQUIRED. The bot's database url. Format: DB_TYPE://PATH_OR_CREDENTIALS/DB_NAME?PARAM1=value&PARAM2=value, you can visit TortoiseORM's documentation to learn more about it
ZIBOT_BOT_MASTERS	botMasters	Separated by spaces. The bot's master(s), allows listed user(s) to execute master/dev only commands. By default it'll get whoever owns the bot application
ZIBOT_ISSUE_CHANNEL	issueChannel	Channel that the bot will use to send reported errors
ZIBOT_OPEN_WEATHER_TOKEN	openweather	Token for OpenWeatherAPI, only required if you want to use the weather command
ZIBOT_AUTHOR	author	Change the bot's author name (and tag) shown in the info command
CURRENTLY NOT AVAILABLE	links	Change the links shown in the info command
CURRENTLY NOT AVAILABLE	TORTOISE_ORM	Advanced TortoiseORM configuration, you shouldn't touch it if you're not familiar with TortoiseORM
ZIBOT_INTERNAL_API_HOST	internalApiHost	The bot's internal API
ZIBOT_ZMQ_PUB	zmqPorts	Port for ZeroMQ's Publish
ZIBOT_ZMQ_SUB	zmqPorts	Port for ZeroMQ's Subscribe
ZIBOT_ZMQ_REP	zmqPorts	Port for ZeroMQ's Reply
ZIBOT_MIGRATION_DIR	migrationFolder or migrationDir	Z3R0's DB migration directory

Manual

Important

Python 3.10+ (3.10.9 is recommended) is required to host this bot!

• Download this repository by executing git clone https://github.com/ZiRO-Bot/Z3R0.git or click "Code" -> "Download ZIP" (be sure to choose overhaul branch first!)

• Install poetry by executing this command,

  # Windows
  py -m pip install poetry
  
  # Linux
  python3 -m pip install poetry

• After poetry successfully installed, execute this command to install all required dependencies,

  # postgresql
  poetry install --no-dev -E postgresql
  
  # mysql
  poetry install --no-dev -E mysql
  
  # mysql (Using asyncmy instead of aiomysql)
  poetry install --no-dev -E "mysql+asyncmy"

• Copy and paste (or rename) config.py-example to config.py

• Edit all the necessary config value (token, botMasters, and sql)

• Run the bot by executing this command, poetry run bot

• If everything is setup properly, the bot should be online!

Development

• Install poetry pip install poetry then run poetry install
• Install pre-commit then run poetry run pre-commit install
• Start the bot by running poetry run bot
• It is recommended to setup a test unit inside src/test when you added a new command, you can run the test by running poetry run pytest -v
  Read dpytest documentation for more information

Data Migration

poetry run datamigration --source "sqlite://data/databaseMigration.db" --dest "postgres://user:pass@host:port/z3r0"

Changelog

Go to the release page to see per-version changelog or CHANGELOG.md for more detailed changelog

Plans

Note

Listed from highest to lowest priority

• Restructure project into a monorepo
• Setup Tests using dpytest
  • Add test for every command
• Rework permissions
  • Currently:
    • Admin = Can configure bot
    • Manage Guild (and Mod role) = Can moderate using the bot
  • Planned:
    • Admin = Full access to bot (except for dev commands ofc)
    • Manage Guild (and Bot Manager role) = Can configure bot
    • Mod role = Bypass every moderator checks like Ban Member, Kick Member, etc
• Rework prefix system
  Currently > is hardcoded as default prefix, this prefix should be added to guild's data when that guild invited the bot)
• Rework issue report system
  Currently reporting error is done manually by the user, but users doesn't seems to bother reporting these errors, even tho all they gotta do is press a button.
  So instead, I probably gonna make the bot report the error manually and keep track if the error already reported before. I'll also strip some information out of the reported messages to respect my user's privacy since issue report is no longer manual.
• i18n
  Implemented, but not yet possible to switch language (other than slash, which tied to the user's client locale settings)
• Event for member boosting a guild (Just need to implement setup for it)
• Tags (stripped version of custom command)
• Unify categories/exts emoji
• Channel manager commands
• Reaction Role (With buttons)
• Starboard
• Slash and ContextMenu commands (80% complete)
• Button-based (or Modal-based?) bot settings

Pending Plan

• Modals
  Too much limitation at the moment, waiting for model input types

Scrapped Plan

Note

Some of these plans are not completely scrapped, some simply scrapped since it's not yet possible for me to do but I don't know whether or not it'll eventually be possible to be added

• Replace mute with the new timeout feature from Discord
  The feature is too limited, maybe I'll add timeout command instead
• Music Player
  Not in my top priority, and looking at how aggresive Google is towards music bots... maybe not gonna do it afterall
• Public/Private commands, allowing other user to use each other's command in a different server
  Too complicated, might add it after I finally finish the dashboard
• Twitch and YouTube notification
  Unreliable most of the time, sometimes return duplicates

License

This bot is licensed under Mozilla Public License, v. 2.0 (MPL-2.0)