Developer Guide
Table of Contents
Getting Started
Welcome to the XDiscordUltimate Developer Guide! This guide will help you set up your development environment, understand the codebase, and start contributing to the project.
Prerequisites
Before you begin, ensure you have:
Java 17+ (OpenJDK or Oracle JDK)
Git (for version control)
Gradle 7.0+ (build automation)
Minecraft Server (for testing)
Discord Developer Account (for bot creation)
IDE (IntelliJ IDEA recommended, Eclipse also supported)
Quick Start
Clone the repository:
Build the project:
Run tests:
Development Environment Setup
Java Installation
Option 1: OpenJDK (Recommended)
Linux (Ubuntu/Debian):
Windows:
Download OpenJDK 17 from Adoptium
Run installer and follow instructions
Verify:
java -versionin command prompt
macOS:
Option 2: Oracle JDK
Download from Oracle and install according to platform instructions.
IntelliJ IDEA Setup
Install IntelliJ IDEA:
Download from jetbrains.com
Install with default settings
Import Project:
Open IntelliJ IDEA
Select "Open"
Navigate to XDiscordUltimate folder
Select
build.gradlefileClick "Open as Project"
Configure SDK:
File → Project Structure (Ctrl+Alt+Shift+S)
Project SDK: Select Java 17
Project language level: 17
Configure Gradle:
File → Settings → Build, Execution, Deployment → Build Tools → Gradle
Use Gradle from:
gradle-wrapper.propertiesGradle JVM: Java 17
Eclipse Setup
Install Eclipse IDE for Java Developers
Import Project:
File → Import → Gradle → Existing Gradle Project
Select project root directory
Follow import wizard
Environment Variables
Create a .env file in the project root (optional, for Discord webhook uploads):
Building from Source
Gradle Tasks
Build the project:
Build without running tests:
Clean build artifacts:
Run tests:
Generate Javadoc:
Upload to Discord (requires .env):
Shadow JAR
The project uses Gradle Shadow plugin to create an "uber-JAR" that includes all dependencies:
This creates build/libs/XDiscordUltimate-1.1.0.jar with all dependencies bundled.
Custom Build Tasks
Build specific version:
Build with environment-specific config:
Continuous Build
For development, use continuous build:
This will automatically rebuild when source files change.
Project Structure
Key Directories
commands/: All Minecraft commandsdatabase/: Database access layer (DatabaseManager)discord/: Discord bot integration (JDA)hooks/: Integrations with other pluginslisteners/: Bukkit event listenersmodules/: All feature modulesutils/: Utility classes and helpers
File Responsibilities
XDiscordUltimate.java
Main plugin lifecycle
ModuleManager.java
Module loading and management
DatabaseManager.java
Database operations and schema
DiscordManager.java
Discord bot connection and API
ConfigManager.java
Configuration file management
MessageManager.java
Localized message handling
Contributing Guidelines
Code Contribution Process
Fork the Repository:
Create a Feature Branch:
Make Changes:
Follow code style guidelines
Write tests for new features
Update documentation
Test Your Changes:
Commit Changes:
Push to Fork:
Create Pull Request:
Go to GitHub
Create pull request from your fork
Describe changes and rationale
Pull Request Guidelines
Before Submitting:
PR Description Template:
Issue Reporting
Bug Reports:
Use GitHub Issues
Include Minecraft version
Include plugin version
Include steps to reproduce
Include error logs
Include configuration (sanitized)
Feature Requests:
Use GitHub Issues with "enhancement" label
Describe the feature
Explain use case
Provide configuration examples
API Reference
Plugin API
The plugin provides an API for other plugins to interact with it:
Getting Plugin Instance
Database Access
Module Access
Configuration
Extension API
Custom Modules
Event Hooks
The plugin fires custom events that can be listened to:
PlaceholderAPI Integration
Custom Module Development
Step-by-Step Guide
1. Create Module Class
2. Register Module
Edit ModuleManager.java:
3. Add Configuration
Add to src/main/resources/config.yml:
4. Add Module Documentation
Create src/main/resources/modules/CUSTOM-MODULE.md:
Avoid:
2. Database Operations
Good:
Avoid:
3. Discord Integration
Good:
Avoid:
4. Event Handling
Good:
Avoid:
5. Resource Management
Good:
Avoid:
Testing Guidelines
Unit Testing
Create test class in src/test/java/:
Running Tests
Integration Testing
For integration tests, create test server:
Test Configuration
Add to build.gradle:
Debugging
Enable Debug Mode
In config.yml:
This enables:
Detailed database query logging
Discord API interaction logging
Module lifecycle logging
Configuration loading logging
Logging Best Practices
Use appropriate log levels:
Include context:
IntelliJ Debugging
Set Breakpoints:
Click in gutter next to line number
Red dot = line breakpoint
Green dot = method breakpoint
Start Debug Session:
Right-click on test class
Select "Debug 'ClassName'"
Or click bug icon
Debug Console:
Inspect variables
Evaluate expressions
Step through code (F8, F7, Shift+F8)
Common Debugging Scenarios
Discord Bot Not Connecting
Database Connection Issues
Module Not Loading
Code Style
Java Code Style
Formatting
Indentation: Use 4 spaces (not tabs)
Line Length: Max 120 characters
Braces:
Line Spacing:
Blank line between methods
Blank line between different logical sections
No blank line after opening brace
Naming Conventions
Classes: PascalCase
Methods: camelCase
Variables: camelCase
Constants: UPPER_SNAKE_CASE
Packages: lowercase
Commenting
Javadoc Comments:
Inline Comments:
Method Comments:
Import Organization
Order:
Java standard library
Third-party libraries
Minecraft/Spigot
Plugin classes
No Wildcards:
Code Organization
Field Ordering:
Static constants
Instance variables
Constructors
Public methods
Private methods
Method Ordering:
Public methods first
Private methods after
Helper methods at bottom
XML/HTML Style
YAML Configuration:
HTML in Embeds:
Release Process
Version Numbering
The project uses Semantic Versioning:
MAJOR.MINOR.PATCH
MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)
Examples:
1.0.0- Initial release1.1.0- New features added1.1.1- Bug fixes2.0.0- Breaking changes
Release Checklist
Pre-Release
Update Version:
Edit
build.gradle:version = 'x.y.z'Edit
plugin.yml:version: x.y.z
Update Changelog: Create
CHANGELOG.md:Update README:
Update version badges
Add any new features
Run Tests:
Build Release:
Manual Testing:
Test on test server
Verify all modules work
Check configuration migration
Update Documentation:
API docs
Module docs
Configuration guide
Release
Create Git Tag:
Create GitHub Release:
Go to GitHub → Releases
Click "Create new release"
Select tag
Upload JAR file
Write release notes
Publish
Deploy:
Upload to Discord webhook (automatic via Gradle task)
Update Spigot resource page (if applicable)
Post-Release
Monitor Issues:
Check GitHub Issues
Monitor Discord for problems
Release Hotfixes:
For critical bugs, release patch version (1.1.1)
Follow same process with expedited testing
Update Documentation:
Update version-specific docs
Migrate guides if needed
Troubleshooting
Build Issues
Gradle Download Fails
Problem: Gradle wrapper download fails
Solution:
Compilation Errors
Problem: "Cannot resolve symbol"
Solution:
Check Java version:
java -versionRefresh Gradle project in IDE
Clean and rebuild:
./gradlew clean build
Problem: "Unsupported class file version"
Solution:
Update Java to version 17 or higher
Check Gradle JDK configuration
Test Failures
Problem: Tests fail with "ClassNotFoundException"
Solution:
Runtime Issues
Plugin Won't Load
Check:
Java version (need 17+)
Spigot version (need 1.16.5+)
Configuration syntax errors
Permission errors
Solutions:
Discord Bot Won't Connect
Check:
Bot token is correct
Bot is in server
Bot has necessary permissions
Guild ID is correct
Debug:
Database Connection Fails
Check:
Database server is running
Credentials are correct
Database exists
User has permissions
Debug:
Development Issues
IntelliJ Won't Recognize Gradle Project
Solution:
Close IntelliJ
Delete
.ideafolderReopen IntelliJ
Open as Gradle project
Code Auto-Formatting Messes Up Imports
Solution:
File → Settings → Editor → Code Style → Java
Imports tab
Set "Class count to use import with '*'": 999
Set "Names count to use import with '*'": 999
Gradle Memory Issues
Solution (in gradle.properties):
Additional Resources
Documentation
Tools
Communities
This developer guide provides comprehensive information for developers working on XDiscordUltimate. Keep it updated as the project evolves!
Last updated
