Skip to content
/ Z3R0 Public

An open-source multi-purpose discord bot

License

MPL-2.0, Unknown licenses found

Licenses found

MPL-2.0
LICENSE
Unknown
COPYING.md
Notifications You must be signed in to change notification settings

ZiRO-Bot/Z3R0

Repository files navigation

Z3R0

Z3R0 (codename ziBot)

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

Code style: black Imports: isort License: MPL-2.0 Donate using Librepay
CI: Build and Test

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)