GSGuildSync Docs1.0.0 Alpha · Fabric 1.20.1

SERVER-SIDE FABRIC MOD

GuildSync Documentation

Connect a Fabric Minecraft server to Discord with live server information, slash commands, a configurable chat bridge and secure admin controls.

Alpha release. Test GuildSync on a backup server before production use.

GETTING STARTED

Installation

  1. Install Fabric Loader for Minecraft 1.20.1 on the server.
  2. Install Fabric API for 1.20.1.
  3. Copy GuildSync and Fabric API to the server mods folder.
  4. Start the server once to generate configuration files.
server/
├─ mods/
│  ├─ guildsync-1.0.0+1.20.1.jar
│  └─ fabric-api-*.jar
└─ config/guildsync/
   ├─ config.yml
   ├─ data.yml
   └─ GUILDSYNC_TUTORIAL.md
Java 17 or newer is required. Players do not need GuildSync installed.

GETTING STARTED

Discord bot setup

  1. Create an application in the Discord Developer Portal.
  2. Create a bot and copy its token.
  3. Enable Message Content Intent for the chat bridge.
  4. Invite the bot with the bot and applications.commands scopes.
  5. Enable Developer Mode in Discord and copy the Guild, channel and role IDs.
Keep the token secret. Never publish config.yml while it contains a bot token.

CONFIGURATION

config.yml

bot:
  token: "PUT_YOUR_BOT_TOKEN_HERE"
  guild-id: "YOUR_DISCORD_GUILD_ID"
modules:
  chat-bridge: true
  whitelist: true
  say: false
info-embed:
  channel-id: "YOUR_STATUS_CHANNEL_ID"
chat-bridge:
  channel-id: "YOUR_CHAT_CHANNEL_ID"
security:
  admin-role-ids: ["YOUR_ADMIN_ROLE_ID"]

Edit configuration while the server is stopped, then restart it.

CONFIGURATION

data.yml

GuildSync manages this file. It stores the live status message ID so restarts update the existing Discord embed instead of creating duplicates.

FEATURES

Slash commands

Command Description Admin
/status Server status, TPS and player count. No
/players Lists online players. No
/server Configured server information. No
/info Creates or updates the live embed. Yes
/say Sends Discord text to Minecraft. Yes
/whitelist Add, remove or list whitelist players. Yes

FEATURES

Chat bridge

Enable modules.chat-bridge and set chat-bridge.channel-id. Minecraft player messages are relayed to that Discord channel and Discord messages return to Minecraft.

FEATURES

Whitelist management

Enable modules.whitelist and configure an admin role. 

/whitelist action:add player:ExamplePlayer
/whitelist action:remove player:ExamplePlayer
/whitelist action:list

DEVELOPMENT

Feature list

Current GuildSync development status.

Feature Status Notes
Discord bot connection Complete Token-based bot connection and status.
Server status commands Complete TPS, player list and server information.
Persistent info embed Complete Updates the same message after a restart.
Role-based admin controls Complete Role IDs protect admin commands.
Two-way chat bridge Complete Requires Message Content Intent.
Whitelist management Complete Add, remove and list actions through Discord.
Fabric 1.21.1 port Planned Next Fabric target.
NeoForge port Not planned No NeoForge build is maintained.

DEVELOPMENT

Supported game versions

This page tracks GuildSync ports and support goals. We do not provide release dates; each Minecraft version receives its own mod JAR. Paper is listed for clarity, but it requires a separate plugin implementation rather than a mod port.

Versions Fabric NeoForge Forge Paper
26.3 Planned Planned Planned Planned
26.2 Planned Planned Planned Planned
26.1 Planned Planned Planned Planned
1.21.11 Skipped Unavailable Skipped Unavailable
1.21.10 Skipped Unavailable Skipped Unavailable
1.21.9 Skipped Unavailable Skipped Unavailable
1.21.8 Skipped Unavailable Skipped Unavailable
1.21.7 Skipped Unavailable Skipped Unavailable
1.21.6 Skipped Unavailable Skipped Unavailable
1.21.5 Skipped Unavailable Skipped Unavailable
1.21.4 Skipped Unavailable Skipped Unavailable
1.21.3 Skipped Unavailable Skipped Unavailable
1.21.2 Skipped Unavailable Skipped Unavailable
1.21.1 Planned Planned Planned Planned
1.20.6 Skipped Unavailable Skipped Unavailable
1.20.5 Skipped Unavailable Skipped Unavailable
1.20.4 Skipped Unavailable Skipped Unavailable
1.20.3 Skipped Unavailable Skipped Unavailable
1.20.2 Skipped Unavailable Skipped Unavailable
1.20.1 In Progress (Alpha) Planned Planned Planned

What these statuses mean

  • In Progress: GuildSync is actively being developed or tested for this version.
  • Planned: A target version, but development has not started.
  • Skipped: No backport is planned for this version.
  • Available: A playable release exists, but no active support is promised.
  • Unavailable: No build exists and a port is not planned.

HELP

Troubleshooting

Bot does not come online

Verify the bot token and check GuildSync lines in the server log.

Slash commands are missing

Check the Guild ID and reinvite the bot with applications.commands.

Chat bridge does not receive messages

Enable Message Content Intent and verify the channel ID.

HELP

Security

  • Keep the token private.
  • Use a dedicated Discord role for administrators.
  • Keep destructive/admin modules disabled unless needed.