How to Use the Paper Plugin “TurboAgent”

2026-08-30

TurboAgent (changed from twbridge on 12/7) is a plugin that allows you to control the
Minecraft Java Edition (Paper server) from the Scratch-compatible block editor, TurboWarp.

Its purpose is to reproduce the familiar “block coding × agent operation" from Minecraft: Education Edition (MakeCode)
in a Java Edition Paper environment.

Preparing the Paper Server and Installing the Plugin

1. Prepare a Paper server
   Download the .jar file for the corresponding version from the official Paper website, launch it for the first time, and complete the basic setup.
2. Place twbridge.jar into the plugins folder
   • Hangar (Official Distribution Page)
   • GitHub Repository
3. Start the server
   After starting, the plugins/twbridge/ folder and config.yml will be automatically generated.
4. The following message will be output to the console.

[TWBridge] WebSocket listening on ws://xx.xxx.xxx.xxx:8787
[TWBridge] Extension server running at http://xxx.xxx.xxx.xxx:8788/tw/twbridge.js

These two URLs will be used later on the TurboWarp side.

Configuring config.yml and Pairing

Full Example of config.yml

ws:
  bindAddress: "0.0.0.0"
  port: 8787
  requirePairing: true
  maxMsgPerSecond: 30
  maxMsgBytes: 8192
  originWhitelist:
    - "*"
http:
  enabled: true
  bindAddress: "0.0.0.0"
  port: 8788
  path: "/tw/twbridge.js"
  wsAddress: "127.0.0.1"
  corsAllowOrigins:
    - "*"
  cacheSeconds: 60
pairing:
  enabled: true
  windowSeconds: 60
debug: false

Description of config.yml Items

Section	Key	Description
ws	bindAddress	WebSocket listen address. 0.0.0.0 allows all NICs.
	port	WebSocket listen port (specified in TurboWarp).
	requirePairing	Requires pairing operation before connection.
	maxMsgPerSecond	Maximum number of messages sent per second.
	maxMsgBytes	Maximum byte size per message.
	originWhitelist	Allowed connection origins. "*" allows all.
http	enabled	Enables the HTTP server that distributes the extension JS.
	port	Port number for the extension distribution HTTP server.
	path	Distribution path. Specify this URL in TurboWarp.
	wsAddress	Default WebSocket address guided by the extension.
	corsAllowOrigins	CORS allowed origins.
	cacheSeconds	Cache duration in seconds for the extension JS.
pairing	enabled	Enable/disable the pairing function.
	windowSeconds	Acceptance window duration in seconds after the /twbridge pair command.
debug	—	Enables debug log output.

How to Use WebSocket Pairing

1. Enable pairing.
   Ensure that requirePairing: true and pairing.enabled: true are specified in the settings above.
2. Run the following in the Paper server console:
   /twbridge pair
   Example:
   [TWBridge] Pairing window opened for 60 seconds.
3. Execute the “Connect" block from TurboWarp within this 60-second window.
   If successful, the following will appear on the Paper side:
   [TWBridge] New client paired: 192.168.0.xxx
4. Devices that have been successfully paired once will automatically be allowed to connect from then on.
   To add a new device, run /twbridge pair again.
5. If you want to disable pairing for development or testing, configure it as follows to allow immediate connection without authentication. (Use only for testing within a LAN.)

ws:
    requirePairing: false
pairing:
    enabled: false

Loading Custom JS in TurboWarp Desktop

1. Launch TurboWarp Desktop.
2. Select ⚙️ (gear icon) at the bottom right → “Add Extension" → “Specify URL".
3. Enter the extension URL displayed when starting the Paper server.
   

   http://192.168.0.xxx:8788/tw/twbridge.js

4. If blocks in the “twbridge" or “Minecraft" categories are added, the loading is successful.

How to Use Block Code

Basic Configuration from Connection to Disconnection

You can execute commands by assembling blocks like this.

[Connect (ws://192.168.0.xxx:8787)]
[Send command (say Hello from twbridge!)]
[Disconnect]

In the Paper server chat,

[Server] Hello from twbridge!

If this appears, communication is successful.

WebSocket Connection and Disconnection

Purpose: Connects TurboWarp Desktop to twbridge on the Paper server.
Prerequisite: Matches ws.port in config.yml (e.g., 8787). If requirePairing: true, run /twbridge pair first.

Example: Connect → Check Status → Disconnect

[Connect (ws://192.168.0.xxx:8787)]
[Check if connected]
[Disconnect]

• For “Connect", enter ws://<Server IP or Host>:<Port>.

• “Check if connected" is a boolean reporter (display method depends on the extension).

• Close with “Disconnect" once communication testing is finished.

Sending Minecraft Commands

Purpose: Executes arbitrary Minecraft commands on the Paper server side.
Prerequisite: Must be connected.

Example: Run /say (Minimal example of Connect → Send → Disconnect)

[Connect (ws://192.168.0.xxx:8787)]
[Send command (say Hello from twbridge!)]
[Disconnect]

Success if the following appears in the Paper server chat.

[Server] Hello from twbridge!

• Commands other than /say may yield different results depending on server settings and permissions.

• The general procedure is the same when sending multiple commands sequentially (operational techniques such as waiting are omitted in this article).

Spawning and Despawning Agents

Purpose: Summons or dismisses an agent (working robot) near the player.
Prerequisite: Must be connected.

Example: Summon Agent → Check → Dismiss → Disconnect

[Connect (ws://192.168.0.xxx:8787)]
[Summon agent]
[Dismiss agent]
[Disconnect]

Moving the Agent

v1.1.1: Added Up/Down

Moves the agent forward, backward, left, right, up, or down by 1 block units.
The distance (number of blocks) can be specified numerically.

[Connect (ws://192.168.0.xxx:8787)]
[Summon agent]
[Move agent (forward) (3) blocks]
[Move agent (right) (2) blocks]
[Move agent (up) (1) blocks]
[Disconnect]

• Movement directions can be chosen from “Forward, Backward, Right, Left, Up, Down".
• Distance can be adjusted by changing the number of blocks.
• The direction depends on the agent’s rotation orientation.

Rotating the Agent

v1.1.0: Added Rotation Feature

Rotates the agent left or right on the spot.
Rotation is in 90-degree increments and is reflected in subsequent movement directions.

[Connect (ws://192.168.0.xxx:8787)]
[Summon agent]
[Rotate agent (right)]
[Move agent (forward) (2) blocks]
[Disconnect]

• You can choose from “Right" or “Left".
• Rotation updates the agent’s internal orientation.
• This changes the direction of “Move forward".

Enabling Agent Inventory Slots

Enables a slot for the agent.
This puts it in a state where it can hold items.

[Connect (ws://192.168.0.xxx:8787)]
[Summon agent]
[Enable agent slot <number>]
[Disconnect]

• Specifies the slot number for the agent to hold in its hand.
• Blocks held in the hand can be placed using the block placement code block.

Setting Blocks in Agent Inventory Slots

Sets the specified block in the agent’s slot.

[Connect (ws://192.168.0.xxx:8787)]
[Summon agent]
[Enable agent slot]
[Set slot (1) to block (minecraft:stone)]
[Disconnect]

• Slot numbers start from 1 (with a maximum of 27).
• Specify the block ID (e.g., stone, glass) as a string.

Agent Block Placement (Forward, Backward, Left, Right, Up, Down)

v1.1.0: Added Block Placement Feature

The agent can now place “blocks set in the inventory slot" in any direction: forward, backward, left, right, up, or down.

The coordinates of the placed block change depending on the agent’s orientation and position.
Placement directions can be chosen from the following:

• Forward
• Backward
• Right
• Left
• Up
• Down

[Enable agent slot (1)]
[Set slot (1) with 64 stone blocks]
[Have agent place block (forward)]

• Forward / Backward / Right / Left depend on the agent’s current “orientation".
• Example: After rotating right, the direction of “forward" also changes.
• Up / Down places blocks vertically based on the position where the agent is standing.
• Block placement requires prior execution of Enabling Slot and Setting Block in Slot.

Troubleshooting

Symptom	Checkpoints
Cannot connect	– Are you using the Desktop version of TurboWarp?- Check the IP address and port number.- Are ports (8787/8788) blocked by a firewall?
Cannot load extension	– Check if the URL is correct.- Is http.enabled set to true?
Pairing fails	– Did you connect within 60 seconds after running /twbridge pair?
Commands do not reflect	– Is the connection state maintained?- Executing commands other than /say may require permissions.

Summary & Future Expansion Plans

twbridge is a minimal plugin to bring the appeal of the education edition—
“controlling Minecraft with blocks“—
into the Java Edition Paper server environment.

Currently, it only has basic connection and agent generation functions, but we plan to add the following in the future.

Item	Purpose / Overview
Agent Movement, Rotation, Block Placement / Destruction	Add action blocks close to MakeCode, enabling tasks within the world (movement, orientation change, placement, destruction).
Status Retrieval Blocks (Coordinates, Orientation, etc.)	Retrieve information such as position, orientation, and surrounding blocks to make it easier to build conditional branches and automation logic.
Independent Agent Operation via Threading	Process each agent with a separate thread + independent timer, allowing multiple different actions to proceed concurrently.
wss (Secure WebSocket) Support	Enable secure connection from HTTPS environments and browser-based TurboWarp, expanding operational options.
Enhancement of Connection Logs and Monitoring Functions	Make it easier to track connected clients and operation history, facilitating management and troubleshooting during classes and experiments.

Related Links

Block Code Plugin Related

1. Reproducing the Minecraft: Education “Block Coding × Agent (Working Robot)" Experience in Java Edition Minecraft

PDCA Related

1. Learning the PDCA Cycle through Minecraft — Fostering Thinking Skills While Having Fun
2. Running the PDCA Cycle in Minecraft! The Story of Creating a Whiteboard Plugin to Learn with Children

Paper Server Related

1. How to Build a Minecraft Server: A Paper Server Construction Guide for Learning with Children
2. Until “Automatically” Publishing PaperMC Plugins with GitHub Actions