An interactive Discord companion for Zenless Zone Zero players.
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.
- 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 —
/helpwith per-command and per-category pages. - Status monitoring — an optional companion service keeps a live status
message in a Discord channel and exposes a
/healthendpoint for uptime monitors.
- Complete agent data for every attribute
- Multi-language support via Crowdin
- Mini RPG system
| 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.
- Python 3.11 (the version used by CI)
- A Discord application with a bot user and its token (Developer Portal)
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.lockCopy the template and fill in at least the bot token:
cp .env.example .envDISCORD_BOT_TOKEN=<your-bot-token>
DEBUG=FalsePublic 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.
Run from the repository root, since logs are written relative to the working directory:
python bot.pyTo also run the optional status service (configured via the STATUS_*
variables in .env):
python -m status_serviceSee docs/status-monitoring.md for setup.
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 pytestbot.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.
| 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. |
- Questions and bug reports: GitHub Issues
- Community: support server
Zenless Zone Zero and all related names, characters, and images are the property of their respective owners.
- Banner art: r/ZZZ_Official
- Built with discord.py
