AeThex-Labs/AeThex-Bot-Master
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
AeThex-Bot-Master/aethex-bot/docs/MANUAL.md
sirpiglr fbc5c0533d Add comprehensive guide for bot features and usage 
Add a new manual documentation file (MANUAL.md) detailing bot features, prerequisites, and setup instructions.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: aed2e46d-25bb-4b73-81a1-bb9e8437c261
Replit-Commit-Checkpoint-Type: intermediate_checkpoint
Replit-Commit-Event-Id: 8a63ea01-888e-4ba2-a228-372092576f9e
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/3bdfff67-975a-46ad-9845-fbb6b4a4c4b5/aed2e46d-25bb-4b73-81a1-bb9e8437c261/ZjyNKqu
Replit-Helium-Checkpoint-Created: true
2025-12-08 20:55:22 +00:00

667 lines
15 KiB
Markdown
Raw Blame History

# AeThex Unified Bot Manual
> The complete guide to AeThex Bot - your all-in-one Discord companion for community management, engagement, and security.
---
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Introduction](#introduction)
3. [Getting Started](#getting-started)
4. [The AeThex Ecosystem](#the-aethex-ecosystem)
5. [Community Features](#community-features)
6. [XP & Leveling System](#xp--leveling-system)
7. [Moderation Tools](#moderation-tools)
8. [Auto-Moderation](#auto-moderation)
9. [Server Management](#server-management)
10. [Security (Sentinel)](#security-sentinel)
11. [Admin Configuration](#admin-configuration)
12. [Command Reference](#command-reference)
13. [Troubleshooting](#troubleshooting)
---
## Prerequisites
### Required Setup
Before using all features, ensure the following are configured:
| Requirement | Purpose | Without It |
|-------------|---------|------------|
| `DISCORD_BOT_TOKEN` | Bot authentication | Bot won't start |
| `DISCORD_CLIENT_ID` | Slash command registration | Commands won't work |
| `SUPABASE_URL` | Database connection | Limited features |
| `SUPABASE_SERVICE_ROLE` | Database access | Limited features |
### Feature Availability
**With Supabase configured:**
- Full XP and leveling system
- User verification and profiles
- Moderation logging
- Server configurations (welcome, goodbye, etc.)
- Role panels, giveaways, scheduled messages
- Auto-moderation settings
- Federation mappings and tickets
**Without Supabase:**
- Basic moderation commands (no logging)
- Sentinel anti-nuke protection (RAM-based)
- Utility commands (userinfo, serverinfo, avatar)
- Announcements and polls
### Environment Variables
Set these in your Replit Secrets or `.env` file:
```env
# Required
DISCORD_BOT_TOKEN=your_bot_token
DISCORD_CLIENT_ID=your_client_id
# Recommended
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE=your_service_role_key
# Optional - Realm Guild IDs
HUB_GUILD_ID=
LABS_GUILD_ID=
GAMEFORGE_GUILD_ID=
CORP_GUILD_ID=
FOUNDATION_GUILD_ID=
# Optional - Security
WHITELISTED_USERS=user_id1,user_id2
ALERT_CHANNEL_ID=channel_for_security_alerts
```
---
## Introduction
### What is AeThex Bot?
AeThex Unified Bot is a powerful, all-in-one Discord bot designed specifically for the AeThex community ecosystem. It combines:
- **Community Features** - User verification, profile linking, and cross-platform integration
- **Engagement Tools** - XP system, leveling, leaderboards, and achievements
- **Moderation Suite** - Comprehensive moderation with logging and auto-mod
- **Server Management** - Welcome messages, role panels, giveaways, and more
- **Sentinel Security** - Enterprise-grade anti-nuke protection
### Key Features at a Glance
| Category | Features |
|----------|----------|
| Community | Profile linking, realm selection, cross-platform stats |
| Engagement | XP tracking, daily claims, leaderboards, badges |
| Moderation | Warn, kick, ban, timeout, mod logs, auto-mod |
| Management | Welcome/goodbye, role panels, giveaways, announcements |
| Security | Anti-nuke, heat tracking, federation sync |
---
## Getting Started
### Linking Your Account
To get the full AeThex experience, link your Discord account to your AeThex profile:
```
/verify
```
This connects your Discord to your AeThex.studio or AeThex.foundation account, enabling:
- Unified XP across all platforms
- Cross-platform statistics
- Special badges and rewards
- Realm-specific features
### Setting Your Realm
AeThex has multiple realms (servers) for different purposes. Set your primary realm:
```
/set-realm
```
**Available Realms:**
- **Hub** - Main community gathering place
- **Labs** - Development and experiments
- **GameForge** - Gaming community
- **Corp** - Professional/business discussions
- **Foundation** - Core community initiatives
### Viewing Your Profile
See your complete AeThex profile with stats, badges, and XP:
```
/profile
```
Your profile card shows:
- Avatar and username
- Current level and XP progress
- XP bar with percentage
- Platform badges
- Account verification status
---
## The AeThex Ecosystem
### Cross-Platform Integration
AeThex Bot connects three platforms:
1. **Discord** - Real-time community chat
2. **AeThex.studio** - Creative platform for projects
3. **AeThex.foundation** - Community initiatives and contributions
XP earned on any platform contributes to your unified level!
### Federation System
The federation system allows roles to sync across multiple AeThex servers:
```
/federation link @role # Link a role for cross-server sync
/federation unlink @role # Remove a role from sync
/federation list # View all linked roles
```
This means if you earn a special role in one realm, it can automatically apply to others.
---
## Community Features
### Profile & Stats
| Command | Description |
|---------|-------------|
| `/profile` | View your profile card with XP bar and badges |
| `/stats` | View detailed statistics |
| `/rank` | Quick view of your level and XP |
| `/badges` | View all earned badges |
### Leaderboards
See who's leading the community:
```
/leaderboard
```
Features:
- Medal rankings (🥇 🥈 🥉)
- XP totals and levels
- Progress bars
- Weekly/monthly views
### Community Posts
Share content with the community:
```
/post
```
Posts sync to the AeThex feed and can be viewed across platforms.
### Studio & Foundation
View platform-specific profiles:
```
/studio [@user] # View AeThex Studio profile
/foundation [@user] # View Foundation contributions
```
---
## XP & Leveling System
### How to Earn XP
| Activity | XP Earned | Cooldown |
|----------|-----------|----------|
| Send a message | +5 XP | 60 seconds |
| Daily claim | +50 XP base | 24 hours |
| Daily streak bonus | Up to +100 XP | Cumulative |
| Platform activity | Varies | None |
### Daily Claims
Claim your daily XP bonus:
```
/daily
```
**Streak System:**
- Day 1: +50 XP
- Day 2: +55 XP
- Day 3: +60 XP
- ... up to Day 10+: +100 XP
Missing a day resets your streak!
### Leveling Formula
```
Level = floor(sqrt(XP / 100))
```
**XP Requirements:**
| Level | Total XP Needed |
|-------|-----------------|
| 1 | 100 |
| 2 | 400 |
| 3 | 900 |
| 5 | 2,500 |
| 10 | 10,000 |
| 20 | 40,000 |
| 50 | 250,000 |
### Level Rewards
Admins can set automatic role rewards at certain levels. When you reach the required level, you automatically receive the role!
---
## Moderation Tools
### Quick Reference
| Command | Description | Permission |
|---------|-------------|------------|
| `/warn @user [reason]` | Issue a warning | Moderate Members |
| `/kick @user [reason]` | Kick from server | Kick Members |
| `/ban @user [reason]` | Ban from server | Ban Members |
| `/timeout @user [minutes] [reason]` | Temporary mute | Moderate Members |
### Warnings
```
/warn @user This is a warning
```
Warnings are logged and accumulate. Use `/modlog @user` to view a user's history.
### Moderation Logs
View a user's complete moderation history:
```
/modlog @user
```
Shows all warnings, kicks, bans, and timeouts with:
- Date and time
- Reason
- Moderator who took action
### Audit Log
View recent admin actions in the server:
```
/auditlog
```
---
## Auto-Moderation
### Overview
Auto-mod automatically detects and handles rule violations:
```
/automod
```
### Available Filters
| Filter | Description | Actions |
|--------|-------------|---------|
| **Links** | Block unauthorized URLs | Delete, warn, timeout |
| **Spam** | Detect message flooding | Delete, warn, timeout |
| **Bad Words** | Custom word blacklist | Delete, warn, timeout |
| **Invites** | Block Discord invite links | Delete, warn |
| **Mentions** | Limit mass mentions | Delete, warn |
### Configuration
```
/automod links enable # Enable link filtering
/automod spam threshold 5 # Set spam threshold
/automod badwords add [word] # Add to blacklist
/automod invites enable # Block invite links
/automod mentions limit 5 # Limit mentions per message
```
### Exempt Roles
Certain roles can be exempted from auto-mod:
```
/automod exempt @Moderator
```
---
## Server Management
### Welcome Messages
Greet new members with rich embeds:
```
/config welcome #welcome-channel
```
Welcome messages include:
- Member's avatar
- Personalized greeting
- Server member count
- Beautiful embed design
### Goodbye Messages
Bid farewell to departing members:
```
/config goodbye #goodbye-channel
```
### Auto-Role
Automatically assign a role to new members:
```
/config autorole @Member
```
### Role Panels
Create interactive role selection menus:
```
/rolepanel
```
Features:
- Button-based role selection
- Custom colors and descriptions
- Multiple roles per panel
- Persists after bot restart
### Announcements
Send beautiful announcements with templates:
```
/announce [title] [message]
```
**Templates Available:**
| Type | Color | Use For |
|------|-------|---------|
| Update | Blue | New features, changes |
| Event | Purple | Community events |
| Important | Yellow | Critical notices |
| Highlight | Green | Celebrations |
| Warning | Orange | Alerts |
| Maintenance | Gray | Downtime notices |
### Polls
Create community polls:
```
/poll [question] [options]
```
### Giveaways
Run automated giveaways:
```
/giveaway create [prize] [duration] [winners]
/giveaway end [message_id]
/giveaway reroll [message_id]
```
Features:
- Automatic winner selection
- Entry tracking
- Optional role requirements
- Reroll capability
### Scheduled Messages
Schedule announcements for later:
```
/schedule [time] [channel] [message]
```
---
## Security (Sentinel)
### Anti-Nuke Protection
Sentinel monitors for destructive actions and automatically responds:
| Threat | Detection | Response |
|--------|-----------|----------|
| Mass channel deletion | 3+ in 10 seconds | Remove permissions, alert |
| Mass role deletion | 3+ in 10 seconds | Remove permissions, alert |
| Mass bans | 3+ in 10 seconds | Remove permissions, alert |
| Mass kicks | 3+ in 10 seconds | Remove permissions, alert |
### Heat Tracking
Every user has a "heat" score that increases with suspicious activity:
```
/admin heat @user
```
- Heat accumulates with destructive actions
- Heat decays over time
- Exceeding threshold triggers automatic protection
### Threat Monitoring
View active threats:
```
/admin threats
```
### Whitelisted Users
Server owners can whitelist trusted users who bypass heat tracking:
- Set via `WHITELISTED_USERS` environment variable
- Comma-separated user IDs
### Tickets
Support ticket system for user assistance:
```
/ticket create [reason] # Open a new ticket
/ticket close # Close current ticket
```
---
## Admin Configuration
### Server Setup
Configure your server with `/config`:
| Setting | Command | Description |
|---------|---------|-------------|
| Welcome Channel | `/config welcome #channel` | Where welcome messages go |
| Goodbye Channel | `/config goodbye #channel` | Where goodbye messages go |
| Mod Log Channel | `/config modlog #channel` | Where mod actions are logged |
| Level-Up Channel | `/config levelup #channel` | Where level-ups announce |
| Auto-Role | `/config autorole @role` | Role given to new members |
| Verified Role | `/config verified @role` | Role for verified users |
| Level Roles | `/config levelrole @role [level]` | Automatic level rewards |
### View Current Config
```
/config view
```
### Admin Commands
| Command | Description |
|---------|-------------|
| `/admin status` | Bot status and statistics |
| `/admin servers` | View all connected servers |
| `/admin heat @user` | Check user's heat level |
| `/admin threats` | View active threat monitor |
### Custom Embeds
Create custom embeds with the modal builder:
```
/embed
```
Opens a form to set:
- Title
- Description
- Color
- Fields
- Images
- Footer
- Target channel
---
## Command Reference
### Community Commands (10)
| Command | Description |
|---------|-------------|
| `/verify` | Link your Discord account to AeThex |
| `/unlink` | Disconnect your Discord from AeThex |
| `/profile` | View your linked AeThex profile |
| `/set-realm` | Choose your primary realm |
| `/verify-role` | Check your assigned Discord roles |
| `/refresh-roles` | Sync roles based on AeThex profile |
| `/stats` | View your AeThex statistics |
| `/leaderboard` | View top contributors |
| `/post` | Create a community feed post |
| `/help` | View categorized commands |
### Leveling Commands (3)
| Command | Description |
|---------|-------------|
| `/rank` | View your level and XP |
| `/daily` | Claim daily XP bonus |
| `/badges` | View earned badges |
### Moderation Commands (5)
| Command | Description |
|---------|-------------|
| `/warn @user [reason]` | Warn a user |
| `/kick @user [reason]` | Kick a user |
| `/ban @user [reason]` | Ban a user |
| `/timeout @user [minutes] [reason]` | Timeout a user |
| `/modlog @user` | View moderation history |
### Utility Commands (4)
| Command | Description |
|---------|-------------|
| `/userinfo [@user]` | View user information |
| `/serverinfo` | View server statistics |
| `/avatar [@user]` | Get user's avatar |
| `/embed` | Create custom embeds |
### Admin Commands (9)
| Command | Description |
|---------|-------------|
| `/config` | Server configuration |
| `/announce` | Send announcements |
| `/poll` | Create community poll |
| `/auditlog` | View admin action history |
| `/rolepanel` | Create role panels |
| `/giveaway` | Giveaway management |
| `/schedule` | Schedule messages |
| `/automod` | Auto-moderation settings |
| `/admin` | Bot administration |
### Cross-Platform Commands (2)
| Command | Description |
|---------|-------------|
| `/studio [@user]` | View AeThex Studio profile |
| `/foundation [@user]` | View Foundation contributions |
### Security Commands (4)
| Command | Description |
|---------|-------------|
| `/federation` | Federation role management |
| `/ticket` | Support ticket system |
| `/status` | View network status |
| `/admin` | Security monitoring |
---
## Troubleshooting
### Common Issues
**"You are not verified"**
- Use `/verify` to link your AeThex account
- Make sure you have an AeThex.studio or AeThex.foundation account
**"Permission denied"**
- Check if you have the required Discord permissions
- Some commands are admin-only
**"Command not responding"**
- The bot may be restarting
- Try again in a few seconds
- Check `/status` for bot status
**"XP not updating"**
- XP has a 60-second cooldown between messages
- Make sure you're in an XP-enabled channel
**"Level-up not announced"**
- Check if a level-up channel is configured
- Use `/config view` to verify settings
### Getting Help
1. Use `/help` to see all available commands
2. Create a support ticket with `/ticket create`
3. Contact server administrators
4. Visit AeThex.foundation for community support
---
## Version Information
- **Bot Version**: 2.0.0
- **Commands**: 36 total
- **Last Updated**: December 2024
---
*This manual is maintained by the AeThex team. For updates and more information, visit [AeThex.foundation](https://aethex.foundation).*
Reference in a new issue View git blame Copy permalink