Published on
Project Duration: Oct 10 2024 – Apr 22 2025

AvatarDuels

AvatarDuels is a large-scale Minecraft server plugin developed for the AvatarDuels server, built around extending the ProjectKorra ecosystem while introducing custom AI, navigation, duel, and world-management systems.

The project began as a refactoring and integration effort and grew into a more substantial gameplay framework. Its main branch contains 41 commits, beginning on October 10, 2024 and continuing through April 22, 2025.

The repository’s original description captures the project’s intent: to actively update ProjectKorra addons and provide additional functionality for the AvatarDuels server.

Watch the Preview → · GitHub Repository →

Gameplay Preview

Overview

AvatarDuels was developed to sit above the existing ProjectKorra gameplay ecosystem rather than replacing it.

The plugin integrates with existing bending functionality and provides additional systems around it, including:

  • JedCore integration
  • ProjectAddons integration
  • Autonomous AI-controlled benders
  • Duel management
  • Arena restoration through Gaia
  • Navigation and pathfinding
  • AI movement and ability usage

These capabilities are all represented directly in the repository README.

ProjectKorra Integration

A major part of AvatarDuels is its integration with the existing ProjectKorra ecosystem.

The project began with an explicit merge with JedCore on its first recorded commit, followed by the initial refactored ProjectAddons implementation.

The repository build configuration also declares ProjectKorra as a compile-time dependency, alongside Gaia and Multiverse-Core, showing that the plugin is designed to operate as part of a wider Minecraft server stack rather than as an isolated plugin.

The resulting architecture allows AvatarDuels to build on existing bending mechanics while adding higher-level server functionality around them.

Autonomous AI Benders

One of the most ambitious parts of AvatarDuels is its autonomous AI bender.

The repository describes the system as being able to engage opponents in duels across large maps, including fights against other AI-controlled benders.

Development history shows this system progressing from basic AI and ability usage into more structured goal-driven behaviour:

  • AI bending
  • Per-ability configuration
  • Ability usage logic
  • Mobility goals
  • Movement management
  • Duel participation
  • Goal-based decision making
  • Improved navigation

The early AI work appears in the October 14–19 commits, before the project moved into navigation and duel integration later in the month.

Goal-Driven AI

Rather than implementing the AI as a simple collection of scripted behaviours, the project evolved towards goal-oriented decision making.

The commit history includes work such as:

  • Make AbilityUsages properly represent goals
  • Enable AI states dependent on ranges, goalify usages
  • Implement MobilityManager
  • Implement Mobility goals and AirBlast usage

This indicates a progression towards representing combat actions and movement as goals that the AI can reason about rather than relying exclusively on hard-coded sequences.

This architecture is particularly useful for an ability-driven game because different bending abilities can produce very different spatial and combat requirements.

AI benders needed to operate across much larger spaces than a single combat arena.

To support this, AvatarDuels developed its own navigation pipeline.

The repository history includes implementations of:

  • BFS-based NavMesh generation
  • A pathfinding*
  • Dijkstra’s algorithm
  • Height-aware navigation
  • Custom heightmaps
  • Improved navigation and sensing

A key commit explicitly describes the system as implementing Dijkstra for milestone management and A* for navigation, with BFS used to generate a NavMesh.

Further work then addressed problems with A* when terrain height changed and improved navigation and sensing behaviour.

AI Movement

Movement was treated as a distinct system within the AI architecture.

The project introduced a MobilityManager and subsequently added mobility goals and ability usage associated with movement.

This was important because bending abilities can themselves function as movement mechanics.

The development history, for example, includes implementations for:

  • AirScooter
  • AirBlast
  • FireJet
  • EarthSurf
  • Catapult

These mechanics could therefore become part of the AI’s available movement and combat toolkit rather than being restricted to direct player input.

Duel System

AvatarDuels includes a dedicated duel framework for organising combat encounters.

The repository README describes it as a basic duel system, while the commit history shows the duel functionality evolving alongside the AI system.

This allowed the same combat infrastructure to support both player-controlled and AI-controlled participants.

The combination of duels, AI decision making, and navigation is what allows an AI bender to operate across an arena rather than simply standing in place and triggering abilities.

Arena Restoration

A major practical problem with large Minecraft battles is dealing with the world changes created during combat.

AvatarDuels addresses this by integrating Gaia for arena restoration. The repository README specifically lists arena reverting through Gaia as one of the project’s core features.

The commit history also shows a dedicated implementation of Gaia arena functionality during the initial duel-system development.

This makes repeated matches practical without requiring arenas to remain permanently altered after every battle.

Ability Usage

The AI system is closely connected to the bending ability system.

The repository history contains dedicated work around AbilityUsages, including changing those usages to properly represent AI goals and adding per-ability configuration.

This provides a useful abstraction between what an ability does and why the AI wants to use it.

For example, an ability can form part of a movement strategy, a combat response, or another AI goal rather than simply being exposed as a generic action.

AI-vs-AI Combat

An important demonstration of the system is that the autonomous bender is not limited to fighting human players.

The repository README explicitly states that AI benders can engage other AI-controlled benders in duels across large maps.

This creates a useful test case for the underlying systems because the AI must handle both navigation and combat without relying on human input.

It effectively turns the duel system into a simulation environment for autonomous bending behaviour.

Project Structure and Build System

AvatarDuels is implemented as a Java plugin using a Gradle Kotlin build configuration.

The current build uses:

  • Java 21
  • Paperweight
  • Shadow
  • Gradle
  • Paper 1.21.1 development APIs

The build also includes dependencies for ProjectKorra, Gaia, Multiverse-Core, and supporting libraries.

The source is organised under:

src/main/java/com/serene/avatarduels
src/main/resources

with the repository also containing Gradle wrapper files, build configuration, and project-specific resources.

Development Evolution

The project’s development history shows a fairly clear progression.

Foundation

Development began on October 10, 2024 with the initial refactored ProjectAddons implementation and a merge with JedCore.

AI

During October 14–19, the project moved into AI bending, ability usage, and goal-based behaviour.

Duels and Mobility

On October 20 and October 28, duel functionality, mobility systems, AI duel usage, and several movement abilities were implemented.

The project then expanded its AI navigation stack with BFS NavMesh generation, A*, Dijkstra, sensing improvements, and height-aware navigation.

Refinement

Later work focused on fine-tuning ability logic, improving commands, fixing movement and sensing issues, and working on milestones. The latest recorded commits in the repository are from April 22, 2025.

Technical Challenges

The most interesting engineering problems in AvatarDuels came from combining systems that were originally designed independently.

The plugin needed to make:

ProjectKorra abilities + AI decision making + navigation + mobility + duels + world restoration

operate together as a coherent gameplay system.

Navigation was particularly important because the AI needed to reason about both horizontal movement and changing terrain height. The commit history explicitly records fixes for A* incorrectly handling height changes, showing that the navigation implementation had to be adapted to the terrain characteristics of Minecraft.

Technical Details

Language: Java Platform: Minecraft Server API: Paper Java Version: 21 Build System: Gradle / Kotlin DSL ProjectKorra: Integrated JedCore: Integrated ProjectAddons: Integrated AI: Autonomous benders and goal-based ability usage Navigation: BFS NavMesh generation, A*, Dijkstra Combat: Player and AI duels Mobility: AI-driven movement abilities World Management: Gaia arena restoration Additional Integration: Multiverse-Core

The current build configuration confirms Java 21, Paper 1.21.1 development tooling, ProjectKorra, Gaia, and Multiverse-Core dependencies.

Project Outcome

AvatarDuels became considerably more than a conventional Minecraft duel plugin.

The final system combines the ProjectKorra bending ecosystem with autonomous AI, custom navigation, mobility systems, duel management, and arena restoration.

The most technically interesting aspect is the interaction between these systems: AI benders can select and use abilities, navigate large environments, participate in duels, and fight other autonomous opponents while the surrounding arena can subsequently be restored.

This makes AvatarDuels an exploration of how far a server-side Minecraft plugin can extend an existing gameplay ecosystem into something closer to a custom combat simulation.

Development Period

October 10, 2024 – April 22, 2025

Ongoing development across 41 commits