PlayerBatch-ExtAPI

Public extension API for PlayerBatch

PlayerBatch-ExtAPI is the public contract for building add-ons on top of PlayerBatch.

PlayerBatch is already a Carpet addon. This repo gives other developers a clean second layer so they can extend PlayerBatch without patching its private internals.

Why This Exists

Without a public API, extension mods usually end up doing one of these:

• hard-depending on private classes
• copy-pasting internals
• mixin-patching random implementation details
• breaking every time the main mod changes

PlayerBatch-ExtAPI exists to stop that.

What Extensions Can Add

Extensions can register:

• custom summon formations
• custom summon arguments
• custom selected-bot actions
• custom post-spawn behaviors
• extra command-side integrations that plug into PlayerBatch

What Works Right Now

The main PlayerBatch mod now consumes this API at runtime.

That means external mods can already:

• register Fabric entrypoints under playerbatch-ext
• add custom formations used by /pb summon
• add custom summon argument handlers
• add custom /pb command ... action handlers
• add custom post-spawn behavior handlers

Core API

Main extension contracts:

• PlayerBatchExtensionEntrypoint
• PlayerBatchRegistrar
• PlayerBatchFormation
• PlayerBatchArgument
• PlayerBatchAction
• PlayerBatchBehavior
• PlayerBatchSummonPlan
• PlayerBatchBotController

Main handler contracts:

• PlayerBatchFormationFactory
• PlayerBatchArgumentHandler
• PlayerBatchActionHandler
• PlayerBatchBehaviorHandler

Quick Start

1. Add the Fabric Entrypoint

Your extension mod should expose a Fabric entrypoint named playerbatch-ext.

{
  "entrypoints": {
    "playerbatch-ext": [
      "com.example.examplemod.ExampleExtension"
    ]
  }
}

2. Implement the Entrypoint

import com.w4whiskers.playerbatch.extapi.PlayerBatchExtensionEntrypoint;
import com.w4whiskers.playerbatch.extapi.PlayerBatchFormation;
import com.w4whiskers.playerbatch.extapi.PlayerBatchRegistrar;
import com.w4whiskers.playerbatch.extapi.PlayerBatchSpawnPoint;

import java.util.ArrayList;
import java.util.List;

public final class ExampleExtension implements PlayerBatchExtensionEntrypoint {
    @Override
    public void register(PlayerBatchRegistrar registrar) {
        registrar.registerFormation(
                PlayerBatchFormation.builder("spiral")
                        .displayName("Spiral")
                        .description("Spawn bots in a spiral pattern.")
                        .factory((request, context) -> {
                            List<PlayerBatchSpawnPoint> points = new ArrayList<>();
                            for (int i = 0; i < request.count(); i++) {
                                double angle = i * 0.7D;
                                double radius = 1.5D + (i * 0.4D);
                                points.add(new PlayerBatchSpawnPoint(
                                        Math.cos(angle) * radius,
                                        0.0D,
                                        Math.sin(angle) * radius,
                                        0.0F,
                                        0.0F
                                ));
                            }
                            return points;
                        })
                        .build()
        );
    }
}

Using It In Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.w4whiskers.playerbatch:playerbatch-extapi:0.1.0"
}

Extension Ideas

Some examples of what a third-party extension could add:

• spiral or arena_ring formations
• argument packs like -duel{true} or -archer{true}
• action packs like circle_strafe, anchor, or pearl_escape
• behavior modules like guard_owner, kite, or totem_swap

Project Layout

Area	Purpose
PlayerBatchExtensionEntrypoint	main extension entry
PlayerBatchRegistrar	register formations, actions, args, behaviors
PlayerBatchSummonPlan	mutable summon plan used by argument handlers
PlayerBatchBotController	safe runtime bot access for action/behavior hooks
PlayerBatchFormationFactory	custom formation spawn-point generation

Related Repos

• PlayerBatch
• PlayerBatch-ExtAPI

License

MIT