DonutBot/docs/BOT_OPERATIONS.md

Bot Operations

This document describes current control flow and operational expectations.

Startup Sequence

1. Load .env and allow-list.
2. Create mineflayer bot instance.
3. On spawn, set joinPosition.
4. Start security monitor interval.
5. Arm security after delay (SECURITY_ARM_DELAY_MS).

Spawner Loop

Loop starts via POST /api/spawner.

Per cycle:

1. Locate/face nearby spawner block.
2. Open spawner GUI.
3. Move all bones from GUI to inventory.
4. Close GUI.
5. Run /order ZareMate.
6. Open order GUI and click bone order item.
7. Move inventory bones into delivery GUI.
8. Confirm with lime/green glass pane.
9. Wait LOOP_DELAY_MS (default 60s).

Security Logic

Security checks run when securityArmed === true.

Triggers:

• Unauthorized player within SECURITY_RADIUS.
• Nearby block broken event within SECURITY_RADIUS.

On trigger:

1. Stop spawner loop.
2. Try to break spawner until gone.
3. Wait briefly for drops.
4. Attempt to open nearby ender chest.
5. Shift-move spawner items from inventory into chest.
6. Send Discord alert with status.
7. Quit bot.

Ender Chest Stash Notes

• Looks for ender_chest block within 6 blocks.
• If no chest is found, routine logs and continues to quit.
• If no spawner items are present in inventory, stash routine is skipped.

Web API Contract

• GET /api/logs returns:
  • { logs: [{ time, message }, ...] }
• POST /api/spawner returns:
  • { ok: true, running: true } on success
• POST /api/stop returns:
  • { ok: true, running: false } when stopped

Operational Tips

• Keep an accessible ender chest near the bot for emergency stash reliability.
• Keep allowed_players.txt current.
• Enable DEBUG_LOGS=1 while diagnosing GUI slot behavior.
• Confirm webhook mentions are configured as expected in your Discord channel.