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

!panel

Opens the ZygnalBot control panel, where you can manage settings and features.

!setprefix <prefix>

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
Important Setup Note

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.

AI Features Information

The bot includes complete AI command system with all features at no cost. To use AI commands:

  1. Get an OpenAI API key from openai.com
  2. Add funds to your OpenAI account
  3. 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.

01

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
02

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
03

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
04

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)
Why Two Roles?

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

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:

!exportconfig
  1. Request the latest version via ticket in the support server or on The Website
  2. Replace your current .py files with the updated versions
  3. If changes in requirements.txt, replace this too
  4. Push changes to your GitHub repository
  5. Your cloud provider will automatically detect changes and redeploy

After deployment completes, import your settings:

!importconfig <json file>

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
Note

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
Important

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

!load filename

Loads a new extension from the Extensions folder

!unload cogname

Unloads a currently active cog

!reload cogname

Reloads a cog to apply changes without restarting the bot

!listcogs

Lists all currently loaded cogs

!coghelp

Shows detailed help for cog management commands

Security Note

Only the bot owner can use the extension management commands for security reasons.

Main Command: !panel

The !panel command is your gateway to all ZygnalBot features. It provides a comprehensive interface to navigate through all available commands.

Key Benefits
  • 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:

  1. Export: Use !exportconfig to generate a basic config file for your server.
  2. Update: Replace your current .py files with the updated versions (usually Main_bot_3.py and others).
  3. Import: Use !importconfig to restore your settings properly.
Important

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)
Known Issues

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": []
}
DM Commands

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.

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.