Skip to content

About

A simple Discord bot for Zenless Zone Zero players, written in Python using the discord.py library. The bot provides game-related information.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Miyabi Bot banner

Miyabi Bot

An interactive Discord companion for Zenless Zone Zero players.

CI Python 3.11 discord.py 2.x Support server

Features • Commands • Getting started • Development • Documentation


Miyabi Bot is a Discord bot written in Python with discord.py. It provides game information through slash commands with nested select menus, pagination, and autocomplete. All responses are ephemeral, so they don't clutter server channels.

Note

Miyabi Bot is an unofficial community project. It is not affiliated with, endorsed by, or sponsored by HoYoverse or Discord.

Features

  • Agent wiki — browse agents by attribute, or jump straight to one with autocomplete (/characters agent:Alice).
  • Interactive navigation — nested select menus with Back, plus button pagination for long sections.
  • Built-in help — /help with per-command and per-category pages.
  • Status monitoring — an optional companion service keeps a live status message in a Discord channel and exposes a /health endpoint for uptime monitors.

Roadmap

  • Complete agent data for every attribute
  • Multi-language support via Crowdin
  • Mini RPG system

Commands

Command Description
/characters [agent] Zenless Zone Zero agent wiki with menu navigation and autocomplete.
/help [command] [category] Help for commands and categories.
/info Bot version, developer, and useful links.

Developer-only test commands (/ping, /pagination_test, /deep_menu) are loaded only when DEBUG=True. See docs/commands.md for details.

Getting started

Prerequisites

  • Python 3.11 (the version used by CI)
  • A Discord application with a bot user and its token (Developer Portal)

Installation

git clone https://github.com/IndiMops/Miyabi-bot.git
cd Miyabi-bot

python -m venv venv
# Windows: .\venv\Scripts\Activate.ps1
# Linux/macOS: source venv/bin/activate

python -m pip install --require-hashes -r requirements.lock

Configuration

Copy the template and fill in at least the bot token:

cp .env.example .env
DISCORD_BOT_TOKEN=<your-bot-token>
DEBUG=False

Public settings (colors, assets, links, command IDs) live in config.json. The full reference is in docs/configuration.md.

Warning

Keep DEBUG=False outside local testing: debug mode loads the dev commands, which have no owner check.

Running

Run from the repository root, since logs are written relative to the working directory:

python bot.py

To also run the optional status service (configured via the STATUS_* variables in .env):

python -m status_service

See docs/status-monitoring.md for setup.

Development

Install the runtime and dev dependencies from the lock files (pip verifies every package hash) and run the same checks as CI:

python -m pip install --require-hashes -r requirements.lock -r requirements-dev.lock

python -m pip check
python -m compileall -q bot.py cogs embeds utils views status_service
python -m ruff check --select E9,F63,F7,F82 .
python -m pytest

Project structure

bot.py            Entry point: client setup, extension loading, command sync
cogs/             Slash commands (every .py file is auto-loaded as an extension)
embeds/           Static embeds and navigation trees
views/            Reusable UI: nested select menus and pagination
utils/            Config, logging, heartbeat, and helpers
status_service/   Standalone status monitoring service
tests/            Unit tests
docs/             Technical documentation

How to add a command or a new agent page is described in docs/architecture.md.

Documentation

Guide Contents
Getting started Environment setup and the first run.
Configuration .env variables and config.json fields.
Architecture Startup lifecycle, layers, and the navigation contract.
Commands Command reference and current limitations.
Development Checks, CI, logs, and troubleshooting.
Status monitoring Heartbeat and the status service.

Support

Legal

Zenless Zone Zero and all related names, characters, and images are the property of their respective owners.

Acknowledgements

About

A simple Discord bot for Zenless Zone Zero players, written in Python using the discord.py library. The bot provides game-related information.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages