Skip to content

Commit aa7ecc0

Browse files
SkyKingPXSkyKingPX
committed
2.0.0-rc6
* Comment entire codebase using Warp AI * Adjusted Bot config * Reworked Console logging & Embeds
1 parent ebc918d commit aa7ecc0

27 files changed

Lines changed: 1570 additions & 382 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,4 @@ votes.json
4747
/.idea/copilot.data.migration.agent.xml
4848
/.idea/copilot.data.migration.edit.xml
4949
/tickets.json
50+
/.idea/

‎WARP.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# WARP.md
2+
3+
This file provides guidance to WARP (warp.dev) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
PhoenixBot is a Discord bot built with Java 21 using JDA (Java Discord API) for handling Discord interactions. The bot provides ticket management, voting systems, FAQ handling, and support for "The Broken Script" modpack community.
8+
9+
## Development Commands
10+
11+
### Build & Run
12+
- **Build**: `.\gradlew.bat build` (Windows) or `./gradlew build` (Unix)
13+
- **Run**: `.\gradlew.bat run` (Windows) or `./gradlew run` (Unix)
14+
- **Build Shadow JAR**: `.\gradlew.bat shadowJar` (Windows) or `./gradlew shadowJar` (Unix)
15+
16+
### Testing
17+
- **Run all tests**: `.\gradlew.bat test` (Windows) or `./gradlew test` (Unix)
18+
- **Run specific test**: `.\gradlew.bat test --tests "TestClassName"` (Windows) or `./gradlew test --tests "TestClassName"` (Unix)
19+
20+
### Development
21+
- **Clean build**: `.\gradlew.bat clean build` (Windows) or `./gradlew clean build` (Unix)
22+
- **Continuous build**: `.\gradlew.bat build --continuous` (Windows) or `./gradlew build --continuous` (Unix)
23+
24+
## Architecture Overview
25+
26+
### Core Components
27+
28+
#### Configuration System
29+
- **Config.java**: Central configuration management using YAML (SnakeYAML)
30+
- **config.yml**: Auto-generated configuration file with Discord IDs and bot settings
31+
- Singleton pattern for configuration access with automatic default config creation
32+
- Supports hot-reloading via `/reloadconfig` command
33+
34+
#### Storage Layer
35+
- **VoteStorage.java**: JSON-based persistent storage for suggestion voting data
36+
- **TicketStorage.java**: JSON-based storage for ticket management with global counters
37+
- Uses Jackson for JSON serialization/deserialization
38+
- Thread-safe synchronized operations for concurrent access
39+
40+
#### Event-Driven Architecture
41+
The bot follows JDA's event-driven pattern with specialized listener classes:
42+
43+
**Core Listeners:**
44+
- **Listener.java**: Main ready event handler, command registration, and bot initialization
45+
- **SupportListener.java**: Handles support forum thread creation and closing
46+
- **SuggestionListener.java**: Manages voting on suggestion forum posts
47+
- **BugReportListener.java**: Processes bug report submissions
48+
- **ThreadDeleteListener.java**: Cleanup when threads are deleted
49+
50+
**Ticket System:**
51+
- **Panel.java**: Ticket panel creation, button interactions, and automated ticket lifecycle
52+
- **TicketCloseHandler.java**: Handles ticket closing confirmations and cleanup
53+
- **CloseHandler.java**: Generic close handling for forum posts
54+
55+
#### Command System
56+
- **CommandRegistry.java**: Central slash command registration
57+
- Individual command classes (InfoCommand, FAQCommand, TBSCommand, CloseCommand)
58+
- Commands are registered as event listeners in the main Bot class
59+
60+
### Data Flow
61+
62+
1. **Bot Initialization**: Config loads → Storage initializes → Commands register → Event listeners attach
63+
2. **Ticket Creation**: User clicks panel button → Thread creates → Storage saves → Auto-delete schedules
64+
3. **Ticket Response**: User responds → Auto-delete cancels → Moderators ping → Storage updates
65+
4. **Vote Management**: User votes → Storage updates → Vote counts sync with Discord reactions
66+
5. **Configuration Changes**: `/reloadconfig` → Config reloads → All components refresh
67+
68+
### Key Design Patterns
69+
70+
#### Singleton Pattern
71+
- **Config**: Single instance with lazy initialization and reload capability
72+
73+
#### Observer Pattern
74+
- JDA event listeners for Discord events (messages, interactions, thread events)
75+
76+
#### Strategy Pattern
77+
- Different handlers for different forum types (support, suggestions, bug reports)
78+
79+
#### Factory Pattern
80+
- Ticket name generation with global counters and username sanitization
81+
82+
### Storage Architecture
83+
84+
#### Persistent Storage
85+
- **votes.json**: Stores vote data per thread with user voting history
86+
- **tickets.json**: Stores ticket metadata, creation times, and response status
87+
- **config.yml**: Bot configuration with Discord channel/role IDs
88+
89+
#### In-Memory Storage
90+
- **pendingTickets**: ConcurrentHashMap tracking scheduled ticket deletions
91+
- **scheduler**: ScheduledExecutorService for automated ticket cleanup
92+
93+
### Integration Points
94+
95+
#### Discord Integration
96+
- **JDA Library**: Main Discord API wrapper
97+
- **Slash Commands**: Modern Discord interaction system
98+
- **Forum Channels**: Specialized channel type handling for tickets/suggestions
99+
- **Thread Management**: Automatic thread creation and lifecycle management
100+
101+
#### External Dependencies
102+
- **Jackson**: JSON processing for storage operations
103+
- **SnakeYAML**: YAML configuration parsing
104+
- **Logback**: Structured logging with custom Discord-friendly formatting
105+
- **Apache HttpClient**: HTTP operations for log uploading
106+
107+
## Configuration Notes
108+
109+
The bot expects a `config.yml` file in the root directory. If missing, it auto-generates a template. Key sections:
110+
- **bot**: Token, activity, owner ID, guild ID
111+
- **logging**: Log channel configuration
112+
- **voting/support/bugReport**: Forum channel IDs
113+
- **roles**: Moderator roles for permissions
114+
- **faq**: FAQ channel and entries configuration
115+
- **tickets**: Ping roles for ticket notifications
116+
117+
## Development Guidelines
118+
119+
### Adding New Commands
120+
1. Create command class extending ListenerAdapter
121+
2. Implement onSlashCommandInteraction method
122+
3. Add command to CommandRegistry.registerCommands()
123+
4. Register listener in Bot.main() event listeners list
124+
125+
### Adding New Storage
126+
1. Create storage class following VoteStorage/TicketStorage patterns
127+
2. Use synchronized methods for thread safety
128+
3. Initialize in Bot.initStorage() method
129+
4. Add getter method to Bot class for global access
130+
131+
### Forum Integration
132+
- Each forum type (support, suggestions, bugs) has dedicated listener
133+
- Thread creation triggers automatic embed and button setup
134+
- Use ThreadChannel.getId() for unique identification
135+
- Always check forum channel IDs against configuration
136+
137+
### Error Handling
138+
- Use SLF4J logging with Bot.class logger reference
139+
- Handle IOException for all storage operations
140+
- Provide user-friendly error messages for Discord interactions
141+
- Log errors with context (thread ID, user ID, action attempted)

‎build.gradle.kts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ plugins {
66

77
application.mainClass = "de.skyking_px.PhoenixBot.Bot"
88
group = "de.skyking_px"
9-
version = "2.0.0-rc5"
9+
version = "2.0.0-rc6"
1010

1111
repositories {
1212
mavenCentral()
@@ -30,7 +30,5 @@ tasks.withType<JavaCompile> {
3030
options.encoding = "UTF-8"
3131
options.isIncremental = true
3232

33-
// Set this to the version of java you want to use,
34-
// the minimum required for JDA is 1.8
3533
sourceCompatibility = "21"
3634
}

‎src/main/java/de/skyking_px/PhoenixBot/Bot.java‎

Lines changed: 51 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,44 +9,82 @@
99
import de.skyking_px.PhoenixBot.listener.SuggestionListener;
1010
import de.skyking_px.PhoenixBot.listener.SupportListener;
1111
import de.skyking_px.PhoenixBot.listener.ThreadDeleteListener;
12-
import de.skyking_px.PhoenixBot.storage.VoteStorage;
1312
import de.skyking_px.PhoenixBot.storage.TicketStorage;
13+
import de.skyking_px.PhoenixBot.storage.VoteStorage;
1414
import de.skyking_px.PhoenixBot.ticket.Panel;
15-
import de.skyking_px.PhoenixBot.util.TicketCloseHandler;
16-
import de.skyking_px.PhoenixBot.util.CloseHandler;
17-
import de.skyking_px.PhoenixBot.util.LogUploader;
18-
import de.skyking_px.PhoenixBot.util.Reload;
15+
import de.skyking_px.PhoenixBot.util.*;
1916
import net.dv8tion.jda.api.JDA;
2017
import net.dv8tion.jda.api.JDABuilder;
2118
import net.dv8tion.jda.api.OnlineStatus;
2219
import net.dv8tion.jda.api.entities.Activity;
2320
import net.dv8tion.jda.api.requests.GatewayIntent;
2421

25-
import org.slf4j.Logger;
26-
import org.slf4j.LoggerFactory;
27-
2822
import java.io.IOException;
2923

24+
/**
25+
* Main Bot class for the PhoenixBot Discord application.
26+
* This class initializes the bot, registers event listeners, and configures JDA.
27+
*
28+
* @author SkyKing_PX
29+
*/
3030
public class Bot {
31-
public static final String VERSION = "2.0.0-rc5";
32-
private static final Logger logger = LoggerFactory.getLogger(Bot.class);
31+
/** Current version of the bot */
32+
public static final String VERSION = "2.0.0-rc6";
33+
3334

35+
/** Storage for vote data across suggestion forums */
3436
private static VoteStorage voteStorage;
37+
/** Storage for ticket data and tracking */
3538
private static TicketStorage ticketStorage;
3639

37-
public static void initStorage() throws IOException {
38-
voteStorage = new VoteStorage();
39-
ticketStorage = new TicketStorage();
40+
/**
41+
* Initializes the storage systems for votes and tickets.
42+
* This method must be called before accessing any storage-related functionality.
43+
*
44+
* @throws IOException If there is an error initializing the storage files
45+
*/
46+
public static void initStorage() {
47+
LogUtils.logStorage("Initializing...", "Vote Storage");
48+
try {
49+
voteStorage = new VoteStorage();
50+
} catch (Exception e) {
51+
LogUtils.logFatalException("Error initializing vote storage", e);
52+
}
53+
LogUtils.logStorage("Initialized", "Vote Storage");
54+
LogUtils.logStorage("Initializing...", "Ticket Storage");
55+
try {
56+
ticketStorage = new TicketStorage();
57+
} catch (Exception e) {
58+
LogUtils.logFatalException("Error initializing ticket storage", e);
59+
}
60+
LogUtils.logStorage("Initializing", "Ticket Storage");
4061
}
4162

63+
/**
64+
* Gets the vote storage instance for managing suggestion votes.
65+
*
66+
* @return The vote storage instance
67+
*/
4268
public static VoteStorage getVoteStorage() {
4369
return voteStorage;
4470
}
4571

72+
/**
73+
* Gets the ticket storage instance for managing support tickets.
74+
*
75+
* @return The ticket storage instance
76+
*/
4677
public static TicketStorage getTicketStorage() {
4778
return ticketStorage;
4879
}
4980

81+
/**
82+
* Main entry point for the PhoenixBot application.
83+
* Initializes storage, configures JDA, and registers all event listeners.
84+
*
85+
* @param args Command line arguments (not used)
86+
* @throws Exception If any error occurs during initialization
87+
*/
5088
public static void main(String[] args) throws Exception {
5189
initStorage();
5290

0 commit comments

Comments
 (0)