Fabric

• PokeBadges for Fabric.
• Fabric Loader 0.18.4 or newer.
• Fabric API.
• Architectury API 13.0.8 or newer.
• Java 21 or newer.

NeoForge

• PokeBadges for NeoForge.
• NeoForge 21.1.x.
• Architectury API 13.0.8 or newer.
• Java 21 or newer.

Optional integrations

Accessories and Curios are optional. When present, PokeBadges can detect an equipped Badge Box through those systems. No external Pokémon mod is declared as a hard dependency.

Opening the Badge Box

The Fabric default key is B. The normal keybind flow requires the player to own a Badge Box in the main hand, off hand, inventory, Curios slot or Accessories slot.

The physical Badge Box item can also be used directly. Server integrations may open the interface through /pokebadges open or the public API, depending on the server configuration.

Main page

The main page displays the player's total badge progress and one navigation button for every supported region. Region buttons expose per-region progress and completion state.

Region pages

Each region page shows its active badge slots. Missing badges are rendered as silhouettes, while obtained badges display their normal item appearance.

Badge tooltips can include the region, active order, Gym Leader, Gym type, whether the badge has been obtained and the stored acquisition timestamp.

Current progress and historical backup

PokeBadges stores two related datasets for every player:

Removing a badge through the public remove operation only removes it from current progress. Its historical backup remains available. Full administrative clear commands remove both current and backup data for their scope.

Unova mode

Unova has two selectable badge sets:

• black_white_1 for Black / White 1.
• black_white_2 for Black / White 2.

Only the selected set counts as active region progression. Disabled Unova badges can optionally be hidden from the creative tab.

Withdrawal rules

Badges can only be withdrawn from the Badge Box when both lock_badges_in_badge_box=false and strict_badge_mode=false. The default configuration keeps Badge Box badges locked.

Player commands

Admin commands

Accepted badge IDs

Badge arguments accept either the full identifier such as pokebadges:toxic_unova_badge or the short path toxic_unova_badge. Command suggestions use the shorter form.

Server configuration

config/pokebadges/pokebadges-server.cfg

Older installs using world/serverconfig/pokebadges-server.cfg are detected when the new file does not exist and are migrated into the current config location.

Default server configuration

// PokeBadges server config
lock_badges_in_badge_box=true
strict_badge_mode=false
backup_command_cooldown_seconds=30
unova_badge_set=black_white_2
hide_disabled_unova_badges_in_creative_tab=false
external_open_requires_badge_box=false

Client configuration

config/pokebadges/pokebadges-client.cfg

// PokeBadges client config
badge_discovery_popups=true

badge_discovery_popups controls the custom first-time badge registration popup. The legacy config/pokebadges-client.cfg location is migrated automatically.

Public entry point

net.levelscraft7.pokebadges.api.PokeBadgesApi

All API methods operate on a server-side ServerPlayer.

Example: award a badge

import net.levelscraft7.pokebadges.api.BadgeOperationResult;
import net.levelscraft7.pokebadges.api.PokeBadgesApi;
import net.minecraft.resources.ResourceLocation;
import net.minecraft.server.level.ServerPlayer;

ResourceLocation toxicBadge = ResourceLocation.fromNamespaceAndPath(
    "pokebadges",
    "toxic_unova_badge"
);

BadgeOperationResult result = PokeBadgesApi.awardBadge(player, toxicBadge);
if (result == BadgeOperationResult.SUCCESS) {
    // Badge Box progression was updated successfully.
}

Example: check a region

ResourceLocation kanto = ResourceLocation.fromNamespaceAndPath("pokebadges", "kanto");
boolean completed = PokeBadgesApi.isRegionCompleted(player, kanto)
    == BadgeOperationResult.SUCCESS;

Operation results

Integration rules

• Use PokeBadgesApi instead of reading or modifying BadgeBoxSavedData directly.
• Badge IDs are normal Minecraft ResourceLocation item IDs.
• Region IDs use the pokebadges namespace, for example pokebadges:kanto.
• API award, remove and restore operations emit the corresponding public event callbacks.

Registration class

net.levelscraft7.pokebadges.api.event.PokeBadgesEvents

Example listener

import net.levelscraft7.pokebadges.api.event.PokeBadgesEvents;

AutoCloseable badgeListener = PokeBadgesEvents.registerBadgeAwarded(event -> {
    var player = event.player();
    var badgeId = event.badgeId();
    var region = event.region();
    var source = event.source();
    long obtainedAt = event.obtainedAt();

    // Your integration logic here.
});

// Call badgeListener.close() when your integration unloads.

Event payloads

Action sources

BadgeActionSource tells integrations where the progression change originated:

MANUAL_DEPOSIT
COMMAND
API
RESTORE
ADMIN
UNKNOWN

The B key does nothing

The normal keybind requires a Badge Box somewhere the server can detect it: main hand, off hand, inventory, Curios or Accessories. Also verify that the key has not been rebound or conflicted with another mod.

Can a server open the Badge Box without giving the item?

Yes. By default external_open_requires_badge_box=false, so /pokebadges open, admin external opens and PokeBadgesApi.openBadgeBox can open the interface without the physical item. Set the option to true to enforce ownership.

What is the difference between give and award?

/pokebadges give gives the physical badge item. /pokebadges admin award records progression directly in the player's Badge Box and backup.

Why can a badge not be removed from the Badge Box?

The default server config has lock_badges_in_badge_box=true. Withdrawal is only available when both the lock option and strict mode are disabled.

A player lost badges after a problem. What should staff do?

1. Run /pokebadges admin audit <player>.
2. If historical backup contains missing progress, run /pokebadges admin restore <player>.
3. Use admin award only when a badge must be granted independently of backup history.

Does PokeBadges require Cobblemon or Pixelmon?

No hard dependency is declared for either project. PokeBadges is built as a standalone badge progression layer and is designed to fit Pokémon-focused environments.

Where should integrations hook progression?

Use PokeBadgesApi for writes and checks, then subscribe to PokeBadgesEvents when your mod needs to react to progression changes. Avoid writing directly to internal SavedData classes.