ZygnalBot Basics
Essential information to get started with your next-gen Discord bot
What is ZygnalBot?
ZygnalBot is a powerful, next-generation Discord bot designed to help with moderation, automation, and community engagement.
Created by TheZ/TheHolyOneZ
Quick Start Commands
Opens the ZygnalBot control panel, where you can manage settings and features.
Changes the bot's command prefix to a custom one.
Example: !setprefix *
Key Features
- Complete moderation suite with ban, kick, mute commands
- Advanced ticket system with customization options
- Server backup and restore capabilities
- Anti-nuke protection system
- JackCoins currency system with games
- AI integration with OpenAI
- Polls and custom embeds
- MoodTracker system for community engagement
Place the bot role directly below the server owner role. This positioning is crucial for the Anti-Nuke system to function properly and ensures the bot can override and prevent unauthorized administrative actions.
The bot includes complete AI command system with all features at no cost. To use AI commands:
- Get an OpenAI API key from openai.com
- Add funds to your OpenAI account
- Insert your API key in the bot's configuration
Choose between GPT-3.5 ($0.002 per message) or GPT-4 ($0.03 per message) based on your needs.
Status Tracker
ZygnalBot includes a status tracker that sends a random token every 10 seconds to track usage statistics. It only sends your Discord Guild ID to ensure instances are not mixed up.
A unique random token acts as an identifier, allowing the bot to report its status across multiple servers without confusion.
Bot Permissions
Essential setup guide for proper bot functionality
Create Bot Roles
For optimal functionality, ZygnalBot requires two specific roles:
- Bot Role (Top Hierarchy) - Contains all permissions needed for operation
- Secondary Role (Bottom Hierarchy) - Used for organizational purposes
Configure Top Role
The main bot role needs specific permissions and positioning:
- Go to Server Settings > Roles
- Create a "Bot Permissions" role
- Enable all required permissions (Admin recommended for full functionality)
- Move this role to the top of hierarchy, just below the server owner
- This positioning is crucial for the Anti-Nuke system to function properly
Setup Secondary Role
The secondary role controls the bot's position in the member list:
- Create a second organizational role
- No permissions are needed for this role
- Place at the bottom of hierarchy or at your preferred position
- This determines the bot's position in the member list
Assigning Roles to the Bot
- Go to your Discord server and click on the Members list
- Find your bot in the list of server members
- Right-click on the bot's name, then click on Roles
- Assign both the Bot Role (top of hierarchy) and Secondary Role (lowest in hierarchy)
This dual-role system serves several important purposes:
- Security: Separates permissions from visual positioning
- Organization: Allows you to control where the bot appears in the member list
- Functionality: Ensures the bot has proper permissions while maintaining your preferred server structure
- Anti-Nuke Protection: The top role position is crucial for the bot to override and prevent unauthorized administrative actions
Deployment Guide
Deploy your ZygnalBot to various cloud platforms
Step 1: Railway Setup
Visit railway.app to get started:
- Create an account or log in
- Click "New Project" button
- Select "Deploy from GitHub repo"
Note: Railway offers a free tier with $5 of usage per month.
Step 2: GitHub Repository
- Create a new private repository
- Upload all your project files
- Include your .env file with configurations
- Make sure all dependencies are included
git push origin main
Step 3: Link Repository
- Click "Connect Repository" in Railway
- Select your GitHub repo from the list
- Authorize Railway access to your GitHub
- Wait for initial deployment to complete
Step 4: Configure Deployment
- Go to Settings in your Railway project
- Find the Deploy section
- Set the start command to run your bot:
python Main_bot_3.py
Step 1: GCP Setup
Visit cloud.google.com to get started:
- Create a Google Cloud account
- Set up billing (required, but has free tier)
- Create a new project from the dashboard
Note: GCP offers a generous free tier and $300 in credits for new users.
Step 2: Cloud Run Setup
- Navigate to Cloud Run in the GCP console
- Click "Create Service"
- Choose "Continuously deploy from source repository"
- Connect to your GitHub repository
Step 3: Configure Dockerfile
Create a Dockerfile in your repository:
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "Main_bot_3.py"]
Step 4: Environment Variables
- In Cloud Run service settings, add your environment variables
- Include your Discord bot token and other required variables
- Set memory allocation to at least 512MB
- Set CPU allocation based on your bot's needs
Step 1: Heroku Setup
Visit heroku.com to get started:
- Create a Heroku account
- Install the Heroku CLI on your computer
- Create a new app from the dashboard
Note: Heroku's free tier has been discontinued. Basic plans start at $5/month.
Step 2: Required Files
Add these files to your repository:
- requirements.txt - List all Python dependencies
- runtime.txt - Specify Python version
- Procfile - Define the startup command
worker: python Main_bot_3.py
Step 3: Deploy to Heroku
Use Git to deploy your bot:
heroku login
git add .
git commit -m "Deploy to Heroku"
git push heroku main
Step 4: Configure Environment
- Go to Settings tab in your Heroku app
- Click "Reveal Config Vars"
- Add your bot token and other environment variables
- Scale your worker dyno to run the bot
heroku ps:scale worker=1
Step 1: Azure Setup
Visit azure.microsoft.com to get started:
- Create a Microsoft Azure account
- Navigate to Azure Portal
- Create a new resource group
Note: Azure offers a free tier with $200 credit for 30 days.
Step 2: App Service Setup
- Create a new App Service
- Select Python as the runtime stack
- Choose your resource group
- Select a pricing tier (Free tier is sufficient for testing)
Step 3: Deployment Center
- Go to Deployment Center in your App Service
- Select GitHub as the source
- Connect to your GitHub repository
- Configure the build provider (Kudu)
Step 4: Configuration
- Go to Configuration in your App Service
- Add application settings for your environment variables
- Set the startup command in General Settings
python Main_bot_3.py
Version Updates
When updating your bot to a new version, follow these steps:
First, export your current configuration:
- Request the latest version via ticket in the support server or on The Website
- Replace your current .py files with the updated versions
- If changes in requirements.txt, replace this too
- Push changes to your GitHub repository
- Your cloud provider will automatically detect changes and redeploy
After deployment completes, import your settings:
Extensions System
Create and load custom cogs without restarting your bot
Introduction to Extensions
The ZygnalBot Extensions System allows you to create and load custom cogs (modules) without restarting your bot. This powerful feature enables you to:
- Add new commands and features on-the-fly
- Test new functionality without restarting
- Organize your bot's features into modular components
- Share and import extensions from other developers
Extensions are loaded from the "Extensions" folder in your bot's root directory. Each extension is a Python file containing a cog class and a setup function.
Extension Dependencies
To use extensions in ZygnalBot, you'll need to install several Python packages:
Pillow
aiohttp
jsonschema
matplotlib
pytz
python-dateutil
aiofiles
If you're using Railway or GitHub for deployment, add these dependencies to your requirements.txt file. If you encounter a "ModuleNotFoundError" in your logs, install the missing module and add it to requirements.txt.
Basic Extension Structure
Each extension is a Python file with a specific structure:
import discord
from discord.ext import commands
import asyncio
class MyCustomCog(commands.Cog):
def __init__(self, bot):
self.bot = bot
@commands.command(name="hello")
async def hello_command(self, ctx):
"""A simple hello command"""
await ctx.send("Hello from my custom extension!")
def setup(bot):
cog = MyCustomCog(bot)
loop = asyncio.get_event_loop()
loop.create_task(bot.add_cog(cog))
return cog
Management Commands
Loads a new extension from the Extensions folder
Unloads a currently active cog
Reloads a cog to apply changes without restarting the bot
Lists all currently loaded cogs
Shows detailed help for cog management commands
Only the bot owner can use the extension management commands for security reasons.
System Notes
Critical information about configuration, updates, and troubleshooting
Main Command: !panel
The !panel command is your gateway to all ZygnalBot features. It provides a comprehensive interface to navigate through all available commands.
- Access all bot categories in one place
- Easy-to-navigate interface
Simply type !panel in any channel where the bot has permission to respond to get access to the command dashboard.
Update & Configuration Workflow
If you are planning to update ZygnalBot, follow these steps to avoid losing your settings:
- Export: Use !exportconfig to generate a basic config file for your server.
- Update: Replace your current .py files with the updated versions (usually Main_bot_3.py and others).
- Import: Use !importconfig to restore your settings properly.
Your AntiNuke settings will NOT be exported/imported through the config commands. These must be reconfigured manually if wiped.
Make sure your server folder is empty (only necessary files) before importing. You can delete old JSONs if you used exportconfig.
Ticket System Troubleshooting
If the buttons in the tickets stop working after updating ZygnalBot:
- Use !close to manually close the ticket.
- You must reconfigure the ticket system by running !ticketsetup <cmd> or !ticketsetup_json.
Once reconfigured, delete the old ticket setup message/button to prevent conflicts.
Installation Requirements
Make sure to install the requirements:
pip install -r requirements.txt
Python Version Compatibility:
- Supported: Python 3.10 - 3.12.7
- Not Supported: Lower than 3.10
- Unstable: 3.13 (Not working correctly yet)
YouTube Playback: If you see a "please verify you're not a robot" message, it's due to YouTube detecting automated traffic. This often happens on shared hosting like Railway. The bot works fine locally or on a VPS with a clean IP.
Server Image: Make sure your Discord server has an icon/image. Commands like !panel grab the server image, so if it's missing, you may get an error.
Advanced Ticket Setup (JSON)
For ticket setup, you can also use !ticketsetup_json with the following structure:
{
"content": null,
"embeds": [
{
"title": "🤖┆Want ZygnalBot?",
"description": "**Want to request ZygnalBot? Open a ticket!**",
"color": "purple",
"image": {
"url": "YOUR_IMAGE_URL_HERE"
}
}
],
"button_color": "blurple",
"button_label": "Request ZygnalBot",
"button_emoji": "🎉",
"attachments": []
}
If you encounter errors when sending commands to the bot in DMs, you can safely ignore them unless the command is specifically designed for DMs. Most features require server context (permissions, channels) to function.
Video Tutorials
Watch comprehensive guides to learn ZygnalBot features
Coming Soon
Video tutorials are currently being prepared. Check back soon for comprehensive visual guides on:
- Initial bot setup and configuration
- Setting up the ticket system
- Configuring moderation features
- Using the backup and restore system
- Creating custom extensions
- Deploying to cloud platforms
In the meantime, join our Discord support server for live help and community tutorials.