Github

WebhookCraft1.0.0.jar

WebhookCraft – Discord Bridge (GTNH/Forge 1.7.10)

This guide explains how to install and configure WebhookCraft, the mod that:

• Sends Minecraft server events to Discord via webhooks.

• Launches a packaged Python Discord bot that:

  • Bridges chat between Discord ↔ Minecraft.

  • Lets authorized users run Minecraft commands from Discord.

  • Provides utilities like !ping, !status, !list, !cmd, and !help.

Works with modpacks such as GregTech: New Horizons. The mod extracts the Python bot to ./bot in the server root and spins up a local WebSocket bridge to talk to it.

1) Requirements

• Forge 1.7.10 server (GTNH compatible).

• Java 8 on the server.

• Python 3.7+ on the same machine (when bot.enabled = true). With python_command: "auto", the mod auto-detects python3 (Linux/macOS) or py -3 / python.exe (Windows).

• A Discord bot token and/or a Discord webhook URL, depending on your use (bot, webhook, or both).

2) Quick Install

1. Drop the WebhookCraft JAR into the server's mods/ folder.

2. Start the server once and then stop it.

   • The mod creates ./webhookcraft.json in the server root.

   • It also extracts the Python bot into ./bot (based on the packaged bot.index).

3. Edit ./webhookcraft.json and fill in your settings (see Configuration below).

4. Start the server again.

   • Console should show messages like:

     • WS Bridge listening…

     • Python bot launched in ./bot

   • In Discord, try !help, !ping, etc.

GTNH (dev/run): if you run from a run/ directory, both webhookcraft.json and ./bot will be created inside that run/ folder.

3) Configuration (webhookcraft.json)

IMPORTANT: JSON does not allow comments. Remove any // … or trailing commas.

Minimal valid example:

{
  "format": { "server_name": "your_server_name", "include_dimension": false },
  "network": { "timeout_ms": 6000 },

  "webhooks": [
    {
      "name": "discord-main",
      "url": "https://discord.com/api/webhooks/XXXX/XXXXXXXXXXXXXXXXX",
      "enabled": true,
      "events": ["chat","join","leave","death","server_start","server_stop","pvp_kill"]
    }
  ],

  "ws": { "enabled": true, "bind": "127.0.0.1", "port": 8765, "secret": "auto" },

  "debug": { "events": false },

  "bot": {
    "enabled": true,
    "python_command": "auto",
    "workdir": "bot",
    "script_name": "bot_ws_bridge.py",
    "env": {
      "DISCORD_TOKEN": "YOUR_TOKEN",
      "CHANNEL_MAIN": "123456789012345678",
      "ALLOW_PIP": "1",
      "MC_CMD_USERS": "663815222854942721,987654321012345678"
    }
  },

  "active_language": "en",

  "url": [
    "https://i.imgur.com/OXAkYlJ.jpeg",
    "https://i.imgur.com/CgRvwzj.jpeg",
    "https://i.imgur.com/bZ2QRXE.jpeg"
  ],

  "language": {
    "en": {
      "ingame_prefix": "[InGame]",
      "welcome": "Welcome",
      "goodbye": "Goodbye",
      "server_start": "Server started",
      "server_stop": "Server stopped",
 //... rest of data :-)
    }
  }
}

Key fields

• format.server_name: prefix shown in Discord (e.g. [GTNH]).

• format.include_dimension: append (dim X) to certain in-game messages.

• webhooks[].url: a Discord webhook https:// URL. Set "enabled": false if unused.

• ws.*: internal Java ↔ Python bridge. Keep 127.0.0.1:8765 unless you know what you're doing. "secret": "auto" generates a per-boot secret.

• bot.enabled: set to true to launch the packaged Python bot.

• bot.python_command: "auto" tries to detect Python (Linux/macOS: python3, Windows: py -3/python).

• bot.workdir: where the .py files are extracted and executed (default ./bot).

• bot.script_name: bot entry point (bot_ws_bridge.py).

• bot.env:

  • DISCORD_TOKEN: your Discord bot token.

  • CHANNEL_MAIN: numeric Discord channel ID.

  • ALLOW_PIP: "1" allows auto-install of missing Python deps.

  • MC_CMD_USERS: comma-separated Discord user IDs authorized to use !cmd.

4) Discord Bot Commands

• !help – list bot commands.

• !ping – show Discord latency and WS status.

• !status – show bot status and language/avatar info.

• !list – run /list on the server and display online players.

• !cmd – run a Minecraft command and return its output. Restricted to MC_CMD_USERS. (Includes rate limiting/queueing to avoid flood).

5) In-Game Server Commands

• /webhookdebug – enable/disable the EventSniffer (verbose event logging) or show status. (Permission level 2)

• /webhookconfig – manage configuration:

  • set language active en

  • set bot.env DISCORD_TOKEN

  • set bot.env CHANNEL_MAIN 123456789012345678

  • set webhook discord-main.enabled true

  • get ws port

  • save (writes webhookcraft.json)

  • list language / list bot.env / list webhook

6) Bot Packaging

• Python bot files are embedded in the JAR under assets/webhookcraft/bot/.

• assets/webhookcraft/bot.index lists (one per line) which files to extract to ./bot at server start.

• The entry point should be bot_ws_bridge.py (configurable via bot.script_name).

• You can replace the bot with any Python implementation as long as:

  1. The entry point matches bot.script_name.

  2. It reads the expected env vars (DISCORD_TOKEN, CHANNEL_MAIN, WS_URL, WS_SECRET, ALLOW_PIP, MC_CMD_USERS).

  3. It connects via WebSocket to WS_URL and signs with WS_SECRET.

  4. If you change embedded files, update bot.index in the JAR so the extractor copies them.

7) Discord Intents

Enable MESSAGE CONTENT INTENT for your bot in the Discord developer portal so it can read messages and commands.

8) Security Notes

• online-mode=false allows username spoofing; keep it true for public servers.

• Do not share tokens or webhookcraft.json. The mod masks some values in logs.

• Keep the WebSocket bound to 127.0.0.1 if the bot runs on the same host.

9) Troubleshooting

• no protocol: your_webhook → The webhook URL is invalid. Paste a valid Discord https:// webhook or disable the webhook (enabled=false).

• ValueError: invalid literal for int() 'your_channel' → CHANNEL_MAIN must be a numeric channel ID.

• Resource not found: /assets/webhookcraft/bot.index → The JAR lacks bot.index under assets/webhookcraft/. Fix your packaging.

• Bot doesn't start → Check python_command (try "auto"), ensure Python 3 is installed, and inspect [WebhookCraft/PyBot] logs.

• !cmd ignored → Ensure your Discord user ID is listed in MC_CMD_USERS and !ping shows WS ✓ Connected.

10) Update / Uninstall

• Update: replace the JAR in mods/ and restart. By default the extractor does not overwrite existing files in ./bot. To force a refresh, delete ./bot before starting or bump names in bot.index.

• Uninstall: remove the JAR from mods/. Optionally delete webhookcraft.json and ./bot.

If something breaks, start with !ping, then check server logs and [WebhookCraft/PyBot] output.