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

  1. Clone the repository:

  1. Build the project:

  1. Run tests:


Development Environment Setup

Java Installation

Linux (Ubuntu/Debian):

Windows:

  1. Download OpenJDK 17 from Adoptium

  2. Run installer and follow instructions

  3. Verify: java -version in command prompt

macOS:

Option 2: Oracle JDK

Download from Oracle and install according to platform instructions.

IntelliJ IDEA Setup

  1. Install IntelliJ IDEA:

  2. Import Project:

    • Open IntelliJ IDEA

    • Select "Open"

    • Navigate to XDiscordUltimate folder

    • Select build.gradle file

    • Click "Open as Project"

  3. Configure SDK:

    • File → Project Structure (Ctrl+Alt+Shift+S)

    • Project SDK: Select Java 17

    • Project language level: 17

  4. Configure Gradle:

    • File → Settings → Build, Execution, Deployment → Build Tools → Gradle

    • Use Gradle from: gradle-wrapper.properties

    • Gradle JVM: Java 17

Eclipse Setup

  1. Install Eclipse IDE for Java Developers

  2. 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 commands

  • database/: Database access layer (DatabaseManager)

  • discord/: Discord bot integration (JDA)

  • hooks/: Integrations with other plugins

  • listeners/: Bukkit event listeners

  • modules/: All feature modules

  • utils/: Utility classes and helpers

File Responsibilities

File
Responsibility

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

  1. Fork the Repository:

  2. Create a Feature Branch:

  3. Make Changes:

    • Follow code style guidelines

    • Write tests for new features

    • Update documentation

  4. Test Your Changes:

  5. Commit Changes:

  6. Push to Fork:

  7. 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:

  1. Click in gutter next to line number

  2. Red dot = line breakpoint

  3. Green dot = method breakpoint

Start Debug Session:

  1. Right-click on test class

  2. Select "Debug 'ClassName'"

  3. 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:

  1. Java standard library

  2. Third-party libraries

  3. Minecraft/Spigot

  4. Plugin classes

No Wildcards:

Code Organization

Field Ordering:

  1. Static constants

  2. Instance variables

  3. Constructors

  4. Public methods

  5. 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 release

  • 1.1.0 - New features added

  • 1.1.1 - Bug fixes

  • 2.0.0 - Breaking changes

Release Checklist

Pre-Release

  1. Update Version:

    • Edit build.gradle: version = 'x.y.z'

    • Edit plugin.yml: version: x.y.z

  2. Update Changelog: Create CHANGELOG.md:

  3. Update README:

    • Update version badges

    • Add any new features

  4. Run Tests:

  5. Build Release:

  6. Manual Testing:

    • Test on test server

    • Verify all modules work

    • Check configuration migration

  7. Update Documentation:

    • API docs

    • Module docs

    • Configuration guide

Release

  1. Create Git Tag:

  2. Create GitHub Release:

    • Go to GitHub → Releases

    • Click "Create new release"

    • Select tag

    • Upload JAR file

    • Write release notes

    • Publish

  3. Deploy:

    • Upload to Discord webhook (automatic via Gradle task)

    • Update Spigot resource page (if applicable)

Post-Release

  1. Monitor Issues:

    • Check GitHub Issues

    • Monitor Discord for problems

  2. Release Hotfixes:

    • For critical bugs, release patch version (1.1.1)

    • Follow same process with expedited testing

  3. 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:

  1. Check Java version: java -version

  2. Refresh Gradle project in IDE

  3. 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:

  1. Java version (need 17+)

  2. Spigot version (need 1.16.5+)

  3. Configuration syntax errors

  4. Permission errors

Solutions:

Discord Bot Won't Connect

Check:

  1. Bot token is correct

  2. Bot is in server

  3. Bot has necessary permissions

  4. Guild ID is correct

Debug:

Database Connection Fails

Check:

  1. Database server is running

  2. Credentials are correct

  3. Database exists

  4. User has permissions

Debug:

Development Issues

IntelliJ Won't Recognize Gradle Project

Solution:

  1. Close IntelliJ

  2. Delete .idea folder

  3. Reopen IntelliJ

  4. Open as Gradle project

Code Auto-Formatting Messes Up Imports

Solution:

  1. File → Settings → Editor → Code Style → Java

  2. Imports tab

  3. Set "Class count to use import with '*'": 999

  4. 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