🖥️For Developers

The api module exposes stable, public interfaces for integrating with Modern BedWars — matches, parties, cosmetics and the Redis key catalogue. These are the same types shared across every module.

Match

Match<T extends MatchType> describes a single game. Statuses flow WAITING → STARTING → PLAYING → RESTARTING; the first two are matchmaking phases.

public interface Match<T extends MatchType> {
    @Nullable UUID hostUUID();
    int teamSize();
    int totalCount();
    boolean canCarry(int weight);
    T type();
    String name();
    void status(MatchStatus status);
    MatchStatus status();
    String map();
    int maxPlayers();
    String server();
    Date created();
    void closed(boolean closed);
    boolean closed();
}

public enum MatchStatus {
    WAITING(true),
    STARTING(true),
    PLAYING(false),
    RESTARTING(false);
    // matchmaking() -> true for WAITING/STARTING
}

MatchType abstracts the game mode (Solo, Duo, Trio, Squad):

public interface MatchType {
    String displayName();
    int maxTeams();
    int teamSize();
    int minPlayers();
}

Party

Parties are immutable value objects — the with* methods return a new instance.

public interface Party {
    UUID id();
    boolean isMember(UUID uuid);
    Set<UUID> members();
    UUID leader();
    boolean isLeader(UUID uuid);
    int size();
    Party withLeader(UUID newLeader);
    Party withMember(UUID member);
    Party withoutMember(UUID member);
}

Integrating an external party plugin

PartyProvider is the read-only integration point for external party plugins (Party and Friends, Parties/AlessioDP, or your own). Set it via bootstrap.getPartyManager().setPartyProvider(provider). When set, the built-in Redis party system is bypassed for reads and the Velocity /party command is disabled automatically.

public interface PartyProvider {
    CompletionStage<Optional<Party>> getParty(UUID playerId);
    CompletionStage<Boolean> hasParty(UUID playerId);
    CompletionStage<Boolean> isLeader(UUID playerId);

    static PartyProvider noop(); // disable built-in commands without providing data
}

Use PartyProvider.noop() to disable the built-in party system entirely — e.g. on the Velocity side when a Bukkit-side party plugin handles everything.

Cosmetics

A Cosmetic is a registered, unlockable effect in one of eight categories.

public interface Cosmetic {
    int id();                              // matches the DB id
    String name();                         // internal name
    String displayName();
    List<String> description();
    CosmeticCategory category();
    CosmeticRarity rarity();
    int cost();                            // coin cost to unlock
    boolean isUnlockedByDefault();
    Optional<String> specialPermission();  // permission gate, if any
}

Categories (CosmeticCategory): ARROW_TRAIL, FIREBALL_TRAIL, VICTORY_DANCE, FINAL_KILL_EFFECT, KILL_MESSAGE, BED_BREAK_EFFECT, BED_BREAK_MESSAGE, WOOD_SKIN.

CosmeticManager registers cosmetics and manages per-player unlocks and active selections. Blocking operations return CompletableFutures; there are cached (synchronous) variants for hot paths:

public interface CosmeticManager {
    void registerCosmetic(Cosmetic cosmetic);
    Optional<Cosmetic> getCosmetic(String name);
    Optional<Cosmetic> getCosmetic(int id);
    List<Cosmetic> getCosmeticsByCategory(CosmeticCategory category);
    Collection<Cosmetic> getAllCosmetics();

    CompletableFuture<Boolean> hasUnlocked(UUID player, Cosmetic cosmetic);
    CompletableFuture<Boolean> unlockCosmetic(UUID player, Cosmetic cosmetic);
    CompletableFuture<Boolean> setActiveCosmetic(UUID player, Cosmetic cosmetic);
    void setAndForgetActiveCosmetic(UUID player, Cosmetic cosmetic);   // fire-and-forget
    CompletableFuture<Optional<Cosmetic>> getActiveCosmetic(UUID player, CosmeticCategory category);
    CompletableFuture<List<Cosmetic>> getUnlockedCosmetics(UUID player);

    // Cache-backed, synchronous — safe on the main thread once loadPlayerData completed
    Optional<Cosmetic> getCachedActiveCosmetic(UUID player, CosmeticCategory category);
    Optional<Cosmetic> getCachedEffectiveCosmetic(UUID player, CosmeticCategory category);
    List<Cosmetic> getCachedUnlockedCosmetics(UUID player);

    CompletableFuture<Void> loadPlayerData(UUID player);
    void unloadPlayerData(UUID player);
}

Never block on a CompletableFuture (get() / join()) on the main server thread. Use the cached variants once loadPlayerData has completed, or chain with thenAcceptAsync.

Statistics

StatsType enumerates tracked stats and their PlaceholderAPI names:

Stat	Placeholder
BEDS_BROKEN	BED
KILLS	KILLS
FINAL_KILLS	FINALKILLS
DEATHS	DEATH
FINAL_DEATHS	FINALDEATHS
WINS	WINS
LOSSES	LOSSES
WIN_STREAK	WINSTREAK
MAX_WIN_STREAK	MAXWINSTREAK
TOTAL_KILLS	TOTALKILLS

Redis key catalogue

For diagnostics and low-level integration, RedisKeys centralises every key (%s are format arguments):

Key	Pattern	Holds
BEDWARS_MAPS	bedwars:maps	Broadcast map list
BEDWARS_PLAYER_LOAD	bedwars:player-load:%s	Per-server player load
DISGUISE_NAME	bedwars:disguise	Disguise names
DISGUISE_ACTIVE_NAMES	bedwars:active-disguise	Active disguises
PARTY	party:%s	Party hash (leader + fields)
PARTY_INVITE	party:invite:%s:%s	Party invite data
MATCH	bedwars:match:%s	Match hash
PLAYER_IN_MATCH	bedwars:player:%s	Player → match id
PLAYER_REJOIN	bedwars:rejoin:%s	Rejoin hash (TTL)
SERVER	bedwars:server:%s	Game-server heartbeat (short TTL)

All cross-server traffic is Redis pub/sub via the internal redis-bridge library — there is no BungeeCord plugin-messaging channel.