Player actions

Player actions are short operations for one online bot. They run on the bot game thread and return a typed result. Use durable tasks for work that continues across ticks or reconnects.

Mount and drive vehiclesCopy Anchor Link

The mount action interacts with an entity and waits for the server to confirm the riding state. The dismount action holds sneak until the server confirms that the bot left the vehicle.

const mounted = yield* bot.mount({
  entityId: horseNetworkId,
  hand: Hand.MAIN,
});

yield* bot.setVehicleControl({
  forward: true,
  sprint: true,
  yaw: 90,
});

yield* bot.dismount();

Vehicle controls are persistent inputs. Send false for movement flags you want to release. The returned vehicle reference contains the connection epoch and network ID, so stale references can be rejected after a reconnect.

Update signs and write booksCopy Anchor Link

Sign updates take exactly four plain-text lines. SoulFire verifies the dimension, loaded chunk, block type, and interaction distance before sending the update.

yield* bot.updateSign({
  position: signPosition,
  frontText: true,
  lines: ["Depot", "Iron", "Input", ""],
});

yield* bot.writeBook({
  inventorySlot: 0,
  pages: ["Shift report", "All systems nominal."],
  title: "Night shift",
});

The book slot is a player hotbar index from zero through eight and must contain a writable book. Providing a title signs the book. Page count, page length, and title length are checked against the active Minecraft protocol limits.

Handle server resource packsCopy Anchor Link

Resource-pack offers appear in session.state.resourcePacks in TypeScript and session.state.resource_packs in Python. Each offer includes its ID, URL, hash, required flag, and optional prompt. Send the corresponding protocol status as your downloader moves through its lifecycle.

yield* bot.respondResourcePack({
  packId: offer.packId,
  response: ResourcePackResponse.ACCEPTED,
});

// Download and validate the pack in your application.

yield* bot.respondResourcePack({
  packId: offer.packId,
  response: ResourcePackResponse.SUCCESSFULLY_LOADED,
});

Flight, elytra, and creative inventoryCopy Anchor Link

setFlying only enables flight when the current game mode grants the ability. startElytraFlight requests normal survival elytra flight while the bot is airborne. Minecraft remains authoritative and rejects the request when the equipped item or movement state is invalid. Creative inventory edits require creative mode and accept inventory-menu slots from zero through 45.

yield* bot.setFlying({ flying: true });
yield* bot.startElytraFlight();

yield* bot.setCreativeSlot({
  slot: 36,
  item: { itemId: "minecraft:stone", count: 64 },
});

// Omit item to clear the slot.
yield* bot.setCreativeSlot({ slot: 36 });

await bot.set_flying(True)
await bot.start_elytra_flight()
await bot.set_creative_slot(36, "minecraft:stone", count=64)
await bot.set_creative_slot(36)

Creative slot edits intentionally use item IDs and counts. For exact custom components or version-specific packet fields, use the permission-gated raw protocol API.

Coordinate multiple action callersCopy Anchor Link

Acquire a bot control lease before a sequence that must not be interrupted by another SDK client, script, or automation task.

yield* Effect.scoped(
  Effect.gen(function* () {
    const lease = yield* bot.acquireControlScoped({ ttlSeconds: 30 });
    yield* bot.updateSign({
      position: signPosition,
      frontText: true,
      lines: ["Reserved", lease.value.token.slice(0, 8), "", ""],
    });
  }),
);

All action methods automatically attach the active lease token. The server also claims granular control resources, so unrelated operations can remain independent.