Documentation

API (ExtAPI)

How to use PlayerBatch-ExtAPI to build external add-ons that extend formations, summon arguments, actions, and behaviors.

What ExtAPI Exists For#

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

The goal is to avoid brittle extension patterns like:

  • hard-depending on private classes
  • copying internal code
  • mixin-patching random implementation details
  • breaking every time the main mod changes

What External Mods Can Add#

PlayerBatch currently supports runtime registration for:

  • custom summon formations
  • custom summon argument handlers
  • custom selected-bot actions
  • custom post-spawn behaviors

Fabric Entrypoint#

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

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

Minimal Registration Example#

java
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()
        );
    }
}

Core Contracts#

Main extension contracts:

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

Main handler contracts:

  • PlayerBatchFormationFactory
  • PlayerBatchArgumentHandler
  • PlayerBatchActionHandler
  • PlayerBatchBehaviorHandler

Summon Plan Capabilities#

PlayerBatchSummonPlan gives extensions a controlled place to influence a summon request.

It can currently carry:

  • a formationId
  • arbitrary metadata values
  • behavior IDs
  • post-spawn action strings

This gives extensions a clean way to enrich a summon pipeline without changing the base mod source.

Gradle Dependency#

gradle
repositories {
    mavenCentral()
}

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

Good Extension Ideas#

  • arena-specific formations like arena_ring
  • summon argument packs like -duel{true} or -archer{true}
  • specialized actions such as circle_strafe
  • post-spawn behaviors like guard_owner or kite

Repositories#