Your bot platform, from anywhere.

Remote integration

A Java client, not a Minecraft plugin dependency.

The SDK wraps UltimateBot’s authenticated HTTP endpoints and live event stream. It is designed for standalone Java applications, dashboards, network services and test automation.

Server setup

Enable one authenticated endpoint.

Remote access is disabled by default. Configure a strong token, choose the network interface deliberately and restart or reload the supported UltimateBot configuration before connecting.

remote-api:
  enabled: true
  host: "127.0.0.1"
  port: 8765
  base-path: "/ultimatebot/api/v1"
  token: "replace-with-a-long-random-secret"

Installation

Add the SDK to a Java 21 application.

The published artifact brings its shared UltimateBot models and JSON runtime transitively. No Paper or Minecraft dependency is required.

repositories {
    maven("https://repo.monkeymoon104.it/releases")
}

dependencies {
    implementation("com.monkey.ultimatebot:sdk:2.0.0")
}

<dependency>
    <groupId>com.monkey.ultimatebot</groupId>
    <artifactId>sdk</artifactId>
    <version>2.0.0</version>
</dependency>

Client lifecycle

Build once, close once.

UltimateBotClient owns the remote event bus and may use a supplied HTTP client or ObjectMapper. Prefer one long-lived instance and close it during application shutdown.

UltimateBotClient client = UltimateBotClient.builder()
    .baseUri("https://minecraft.example.com/ultimatebot/api/v1/")
    .token(System.getenv("ULTIMATEBOT_TOKEN"))
    .timeout(Duration.ofSeconds(8))
    .build();

client.health().requireSuccess();

Runtime.getRuntime().addShutdownHook(Thread.ofPlatform().unstarted(client::close));

• baseUri(String|URI) selects the versioned Remote API root
• token(String) is required and validated before construction
• timeout(Duration) controls normal request timeouts
• httpClient(HttpClient) allows managed transport reuse
• objectMapper(ObjectMapper) allows compatible JSON customization
• close() terminates active event subscriptions and workers

Bot requests

Safe defaults, fluent specialization.

Start with an owner-bound or independent factory, override only what the scenario needs, then build an immutable request. Cross-field validation catches invalid modes, ranges and behavior combinations locally.

BotSpawnRequest request = BotSpawnRequest.ownedBy(playerUuid)
    .botNameTemplate("Remote-Trainer")
    .botUUID(customBotUuid)
    .difficulty(DifficultyTier.HARD)
    .combatMode(CombatMode.MACE)
    .targetMode(BotTargetMode.PLAYERS)
    .armor(BotArmorTier.NETHERITE)
    .totemCount(8)
    .autoTargetRange(24.0D)
    .healing(true)
    .explosionBlockDamage(false)
    .emptyEquipmentSlot(SdkBotEquipmentSlot.OFF_HAND)
    .build();

BotOperationResponse response = client.spawnBot(request).requireSuccess();
BotSnapshotResponse spawned = Objects.requireNonNull(
    response.snapshot(), "Successful spawn did not return a snapshot");
UUID botUuid = Objects.requireNonNull(spawned.botUUID(), "Spawned bot UUID is unavailable");

Convenience profiles

Remote operations

Manage the complete runtime surface.

Read operations return immutable response models. Mutation operations return BotOperationResponse with a success flag, message, optional latest snapshot and optional bulk-removal count.

BotSnapshotResponse bot = client.getBot(ownerOrBotUuid);

client.updateCombatModeByBotUUID(bot.botUUID(), CombatMode.CRYSTAL).requireSuccess();
client.updateTargetModeByBotUUID(bot.botUUID(), BotTargetMode.PLAYERS_AND_MOBS).requireSuccess();
client.updateBrain(bot.botUUID(), BrainKey.of("myaddon", "adaptive-ai")).requireSuccess();

client.resetBrain(bot.botUUID()).requireSuccess();
client.removeByBotUUID(bot.botUUID()).requireSuccess();

Server-Sent Events

Live bot events that recover automatically.

The SDK opens a background SSE connection per subscription, reconnects with exponential delay and resumes from the last delivered event ID when the server supports replay.

BotEventSubscription subscription = client.events().subscribeForBot(
    botUuid,
    Set.of(
        SdkBotEventType.ATTACK_STARTED,
        SdkBotEventType.DIED,
        SdkBotEventType.TARGET_CHANGED),
    event -> {
        System.out.printf("%s #%d at %s%n",
            event.type(), event.sequence(), event.occurredAt());

        event.payloadValue("targetUUID", String.class)
            .ifPresent(target -> System.out.println("Target: " + target));
    });

// Later: subscription.close();

• Spawn accepted and completed
• Despawn accepted and completed
• Death and entity kill outcomes
• Target changes and setting acceptance
• Attack, damage and prepared explosions
• Healing, teleport and totem use
• Unknown future types preserved as strings
• Per-bot sequence, event ID and occurrence timestamp

Models and failures

Immutable data with explicit failure paths.

Requests validate before transport, responses are records, optional values are annotated, and protocol/HTTP failures use a dedicated client exception.

try {
    BotOperationResponse response = client.updateDifficulty(botUuid, DifficultyTier.GOD);
    if (!response.success()) {
        logger.warn("Server rejected update: {}", response.message());
    }
} catch (UltimateBotClientException transportFailure) {
    logger.error("UltimateBot endpoint unavailable", transportFailure);
}

Dynamic combat platform

Discover what this server can run.

Combat modes and brains are namespaced values, not a hardcoded remote list. Query the server before presenting choices in a control panel.

List<CombatModeDefinition> modes = client.listCombatModes();
List<BrainDefinition> brains = client.listBrains();
List<AddonInfo> addons = client.listAddons();

modes.stream()
    .filter(CombatModeDefinition::enabled)
    .forEach(mode -> ui.addMode(mode.mode(), mode.displayName()));

client.updateCombatModeByBotUUID(botUuid, CombatMode.of("myaddon", "adaptive-duels"));
client.updateBrain(botUuid, BrainKey.of("myaddon", "adaptive-ai"));

Generated from source

Complete SDK reference.

Search every public SDK type generated for version 2.0.0. Open a result for its constructor, builder methods, fields, response contract and nullability details.