{"id":5250,"date":"2026-08-30T12:10:41","date_gmt":"2026-08-30T03:10:41","guid":{"rendered":"https:\/\/donguri3.net\/server-tech\/turboagent-howto-2\/"},"modified":"2026-08-30T12:10:43","modified_gmt":"2026-08-30T03:10:43","slug":"turboagent-howto","status":"publish","type":"post","link":"https:\/\/donguri3.net\/en\/server-tech\/minecraft\/turboagent-howto\/","title":{"rendered":"How to Use the Paper Plugin “TurboAgent”"},"content":{"rendered":"

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

Its purpose is to reproduce the familiar “block coding \u00d7 agent operation” from Minecraft: Education Edition (MakeCode)
\nin a Java Edition Paper environment.<\/p>\n

Preparing the Paper Server and Installing the Plugin<\/h2>\n
    \n
  1. Prepare a Paper server
    \nDownload the .jar file for the corresponding version from the official Paper website, launch it for the first time, and complete the basic setup.<\/li>\n
  2. Place twbridge.jar into the plugins folder\n
      \n
    • Hangar (Official Distribution Page)<\/li>\n
    • GitHub Repository<\/li>\n<\/ul>\n<\/li>\n
    • Start the server
      \nAfter starting, the plugins\/twbridge\/ folder and config.yml will be automatically generated.<\/li>\n
    • The following message will be output to the console.<\/li>\n<\/ol>\n
      [TWBridge] WebSocket listening on ws:\/\/xx.xxx.xxx.xxx:8787\n[TWBridge] Extension server running at http:\/\/xxx.xxx.xxx.xxx:8788\/tw\/twbridge.js<\/pre>\n
      These two URLs will be used later on the TurboWarp side.<\/p>\n
      Configuring config.yml and Pairing<\/h2>\n
      Full Example of config.yml<\/h3>\n
      ws:\n  bindAddress: "0.0.0.0"\n  port: 8787\n  requirePairing: true\n  maxMsgPerSecond: 30\n  maxMsgBytes: 8192\n  originWhitelist:\n    - "*"\nhttp:\n  enabled: true\n  bindAddress: "0.0.0.0"\n  port: 8788\n  path: "\/tw\/twbridge.js"\n  wsAddress: "127.0.0.1"\n  corsAllowOrigins:\n    - "*"\n  cacheSeconds: 60\npairing:\n  enabled: true\n  windowSeconds: 60\ndebug: false\n<\/pre>\n
      Description of config.yml Items<\/h3>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
      Section<\/th>\nKey<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
      ws<\/strong><\/td>\nbindAddress<\/code><\/td>\nWebSocket listen address. 0.0.0.0<\/code> allows all NICs.<\/td>\n<\/tr>\n
      <\/td>\nport<\/code><\/td>\nWebSocket listen port (specified in TurboWarp).<\/td>\n<\/tr>\n
      <\/td>\nrequirePairing<\/code><\/td>\nRequires pairing operation before connection.<\/td>\n<\/tr>\n
      <\/td>\nmaxMsgPerSecond<\/code><\/td>\nMaximum number of messages sent per second.<\/td>\n<\/tr>\n
      <\/td>\nmaxMsgBytes<\/code><\/td>\nMaximum byte size per message.<\/td>\n<\/tr>\n
      <\/td>\noriginWhitelist<\/code><\/td>\nAllowed connection origins. \"*\"<\/code> allows all.<\/td>\n<\/tr>\n
      http<\/strong><\/td>\nenabled<\/code><\/td>\nEnables the HTTP server that distributes the extension JS.<\/td>\n<\/tr>\n
      <\/td>\nport<\/code><\/td>\nPort number for the extension distribution HTTP server.<\/td>\n<\/tr>\n
      <\/td>\npath<\/code><\/td>\nDistribution path. Specify this URL in TurboWarp.<\/td>\n<\/tr>\n
      <\/td>\nwsAddress<\/code><\/td>\nDefault WebSocket address guided by the extension.<\/td>\n<\/tr>\n
      <\/td>\ncorsAllowOrigins<\/code><\/td>\nCORS allowed origins.<\/td>\n<\/tr>\n
      <\/td>\ncacheSeconds<\/code><\/td>\nCache duration in seconds for the extension JS.<\/td>\n<\/tr>\n
      pairing<\/strong><\/td>\nenabled<\/code><\/td>\nEnable\/disable the pairing function.<\/td>\n<\/tr>\n
      <\/td>\nwindowSeconds<\/code><\/td>\nAcceptance window duration in seconds after the \/twbridge pair<\/code> command.<\/td>\n<\/tr>\n
      debug<\/strong><\/td>\n\u2014<\/td>\nEnables debug log output.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
      How to Use WebSocket Pairing<\/h2>\n
        \n
      1. Enable pairing.
        \nEnsure that requirePairing: true<\/code> and pairing.enabled: true<\/code> are specified in the settings above.<\/li>\n
      2. Run the following in the Paper server console:
        \n\/twbridge pair<\/code>
        \nExample:
        \n[TWBridge] Pairing window opened for 60 seconds.<\/code><\/li>\n
      3. Execute the “Connect” block from TurboWarp within this 60-second window.
        \nIf successful, the following will appear on the Paper side:
        \n[TWBridge] New client paired: 192.168.0.xxx<\/li>\n
      4. Devices that have been successfully paired once will automatically be allowed to connect from then on.
        \nTo add a new device, run \/twbridge pair again.<\/li>\n
      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.)<\/li>\n<\/ol>\n
        ws:\n    requirePairing: false\npairing:\n    enabled: false<\/pre>\n
        Loading Custom JS in TurboWarp Desktop<\/h2>\n
          \n
        1. Launch TurboWarp Desktop.<\/li>\n
        2. Select \u2699\ufe0f (gear icon) at the bottom right \u2192 “Add Extension” \u2192 “Specify URL”.<\/li>\n
        3. Enter the extension URL displayed when starting the Paper server.
          \n\n\n\n
          \n
          http:\/\/192.168.0.xxx:8788\/tw\/twbridge.js<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/li>\n
        4. If blocks in the “twbridge” or “Minecraft” categories are added, the loading is successful.<\/span><\/li>\n<\/ol>\n
          How to Use Block Code<\/h2>\n
          Basic Configuration from Connection to Disconnection<\/h3>\n
          You can execute commands by assembling blocks like this.<\/p>\n
          [Connect (ws:\/\/192.168.0.xxx:8787)]\n[Send command (say Hello from twbridge!)]\n[Disconnect]<\/pre>\n
          In the Paper server chat,<\/p>\n
          [Server] Hello from twbridge!<\/pre>\n
          If this appears, communication is successful.<\/p>\n
          WebSocket Connection and Disconnection<\/h3>\n
          Purpose<\/strong>: Connects TurboWarp Desktop to twbridge on the Paper server.
          Prerequisite<\/strong>: Matches ws.port<\/code> in config.yml<\/code> (e.g., 8787). If requirePairing: true<\/code>, run \/twbridge pair<\/code> first.<\/p>\n
          Example: Connect \u2192 Check Status \u2192 Disconnect<\/h3>\n
          \n[Connect (ws:\/\/192.168.0.xxx:8787)]\n[Check if connected]\n[Disconnect]\n<\/pre>\n