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 4a39363dfd Implement a new achievement system for tracking user progress and rewards 
Adds a comprehensive achievement system to the bot, including new triggers for various user actions, the ability to create, manage, and view achievements, and integration with existing XP and leveling systems. This also involves updating user statistics tracking to support achievement triggers.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: aed2e46d-25bb-4b73-81a1-bb9e8437c261
Replit-Commit-Checkpoint-Type: intermediate_checkpoint
Replit-Commit-Event-Id: 28bc7e36-c36d-4b62-b518-bcc2c649398e
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/3bdfff67-975a-46ad-9845-fbb6b4a4c4b5/aed2e46d-25bb-4b73-81a1-bb9e8437c261/yTaZipL
Replit-Helium-Checkpoint-Created: true
2025-12-08 21:47:11 +00:00

705 lines
16 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!
### Achievements
Create custom server achievements with various triggers:
```
/achievements create [name] [trigger] [value]
```
**Available Triggers:**
| Trigger | Description |
|---------|-------------|
| Level | Reach a specific level |
| Prestige | Reach a prestige level |
| Total XP | Earn total XP amount |
| Messages | Send X messages |
| Reactions Given | Give X reactions |
| Reactions Received | Receive X reactions |
| Voice Minutes | Spend X minutes in voice |
| Daily Streak | Achieve X day streak |
| Commands Used | Use X commands |
**Achievement Options:**
- **Icon**: Custom emoji for the achievement
- **Description**: Custom description
- **Reward XP**: XP bonus when earned
- **Reward Role**: Role awarded when earned
- **Hidden**: Hide until earned (secret achievements)
**Commands:**
```
/achievements create [name] [trigger] [value] # Create achievement
/achievements delete [name] # Delete achievement
/achievements list # View all server achievements
/achievements view [@user] # View earned achievements
/achievements grant @user [name] # Manually grant achievement
/achievements revoke @user [name] # Revoke achievement
```
---
## 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