Carpet Bot Manager (cbot)

Fabric mod that adds player-owned bot management on top of Fabric Carpet's /player command.

The mod can run server-side only for command-based management. If the same jar is installed on both the server and the client, players can also manage their own bots through a GUI.

Dependencies

• Minecraft 1.21.11 (Yarn mapped)
• Fabric Loader
• Fabric API
• Fabric Carpet (for /player-based spawn/actions)

Build system: Gradle + Fabric Loom (project files included).

If Carpet is missing, /cbot still registers, but Carpet-backed actions (spawn and forwarded actions) return: Carpet mod is not installed.

Client GUI

Install cbot on both the server and client to enable the GUI.

• /cbot gui
  • Opens the client GUI when the player has the client mod installed.
  • Without the client mod, the server returns Install cbot on your client to use the GUI.
• Keybind: Open Carpet Bot Manager
  • Default is unbound.
  • Configure it in Minecraft controls under Carpet Bot Manager.

The GUI is personal bot management only. Admin configuration remains command-only.

GUI actions are still server-authoritative:

• The client sends only bot IDs and action parameters.
• The server resolves bot ownership from the executing player.
• Bot actions still dispatch only restricted player <ownedBotName> ... or tp <ownedBotName> ... commands.

Commands

• /cbot list
  • Shows owned bot IDs, names, and online status.
• /cbot buy
  • Buys one additional bot using the configured price.
• /cbot gui
  • Opens the client GUI if the client also has cbot installed.
• /cbot <id> spawn
  • Runs player <botName> spawn as server source.
• /cbot <id> tp
  • Runs tp <botName> <playerName>.
• /cbot <id> tp <x> <y> <z>
  • Runs tp <botName> <x> <y> <z>.
• /cbot <id> <carpetAction...>
  • Forwards to player <botName> <carpetAction...>.
  • Provides autocomplete hints for common Carpet actions while still forwarding the action text unchanged.

Admin-only config commands require permission level 4:

• /cbot config show
  • Shows the current bot name pattern, free bot count, price, and cap.
• /cbot config botname "<pattern>"
  • Sets the bot name pattern and renames saved bot identities.
  • Supported placeholders: {player}, {id}, {uuid}.
  • Generated bot names are sanitized and deterministically shortened to Minecraft's 16-character player-name limit.
• /cbot config starting-free <count>
  • Sets how many free bots players are topped up to on next join or /cbot use.
• /cbot config price <item> <count>
  • Sets the buy price, for example minecraft:diamond 2.
  • A count of 0 makes buying free.
• /cbot config cap <count>
  • Sets the maximum total bots per player.
• /cbot config cap none
  • Removes the bot cap.
• /cbot config reset
  • Restores defaults and renames saved bot identities back to the default pattern.

Ownership and persistence

• Ownership is stored per world in a PersistentState:
  • Map<UUID, List<String>> botNames.
• By default, a player gets exactly one starter bot:
  • cbot_<ownerName>_1.
• Additional bots are deterministic and per-owner:
  • cbot_<ownerName>_<n>.
• Defaults:
  • Bot name pattern: cbot_{player}_{id}
  • Starting free bots: 1
  • Price: 1 minecraft:netherite_block
  • Bot cap: none
• Changing botname renames saved identities immediately. Already-spawned old-name fake players are not killed automatically.

Security model

/cbot executes underlying commands with elevated server permissions, but only after validation:

• Executor must be a real ServerPlayerEntity.
• Bot ID must resolve from that player's owned list.
• Commands are restricted to:
  • player <resolvedBotName> ...
  • tp <resolvedBotName> ...
• All dispatches are logged with owner UUID/name, bot name, action, and command string.

This prevents arbitrary command execution through /cbot.

Quick test plan

1. Fresh world: join as PlayerA, run /cbot list, verify 1 starter bot.
2. Run /cbot 1 spawn, verify bot appears.
3. Run /cbot 1 use once, verify forwarding works.
4. Give netherite block, run /cbot buy, verify bot #2 appears in /cbot list.
5. Join PlayerB, verify PlayerB cannot manage PlayerA's bot IDs.
6. Restart server, verify ownership persists.
7. As an operator, run /cbot config starting-free 3, verify an existing player is topped up on the next /cbot list.
8. Run /cbot config botname "cbot{id}_of_{player}", verify saved bot names are renamed and stay spawnable.

E2E tests

Run the Mineflayer-based E2E test with:

npm run e2e

The test starts ./gradlew runServer, ensures Fabric Carpet is available in run/mods, connects real network players with Mineflayer in offline mode, executes /cbot commands, checks chat responses, and stops the server.