Your boss. Your attacks. One reusable battle framework.

Boss Framework API helps Minecraft mod developers build advanced boss encounters without rewriting the surrounding systems. Attach it to an existing server-side LivingEntity, register a definition, and write the attacks that make your boss unique.

What it provides

• Health, time, event and custom phase conditions.
• Timed skills: warning, windup, cast, execution, cooldown and interruption.
• Visible circle, cone and line attack warnings.
• Boss bars with name, health, phase and custom colors.
• Model-independent animation events and intro/death timelines.
• Optional arenas, participant rewards, first-kill history and offline reward delivery.
• Server-authoritative state, late-join snapshots and saved encounter recovery.
• Reloadable datapack JSON definitions and an ExampleBoss integration.

The server controls phases, skills, damage and rewards. Clients display warnings, UI, particles and presentation events. Choose your own entity, model and animation library; no other mod is required.

Try the example

In a world with commands enabled, an operator can run /bossframework example. A vanilla iron golem demonstrates three phases, attack warnings, a purple boss bar, intro/death effects and rewards. The framework does not automatically spawn bosses in existing worlds.

Installation

Choose the file for your exact Minecraft version and Forge version from the Files tab. Each Minecraft port is built and tested independently; a JAR for one version does not support other versions. Install on both client and server. Java 17 is used for Minecraft 1.20.1–1.20.4, Java 21 for 1.20.6–1.21.11, and Java 25 for 26.x. Forge only; Fabric and NeoForge are not supported. MIT license.

For developers

Use BossDefinition, Phase, SkillDefinition, RewardDefinition and BossRegistry; attach the registered definition through BossManager. The example and API documentation are included in the source project. Register definitions during common setup and perform encounter changes on the server thread.

Alpha releases and validation

Published ports are validated with 12 unit tests, 22 framework GameTests, a real dedicated-server save/restart across two processes, a consuming Forge project and two real client rounds (Fancy and Fabulous). Automated coverage includes participant rewards, phase/skill recovery and late-join synchronization; a large live multiplayer server soak test has not been performed.

Normal saved restarts are supported. Arbitrary third-party reward callbacks cannot be guaranteed atomic across hard crashes. Rankings, random affixes, challenge modes and encounter recording are reserved for future work.