TownyDiscordChat

TownyDiscordChat

Automatically manage private Discord communities for your Minecraft towns and nations.

TownyDiscordChat connects Towny Advanced with DiscordSRV, automatically creating and maintaining private Discord roles, text channels, and voice channels for your Minecraft towns and nations.

As players join towns, change nations, or leave communities, TownyDiscordChat keeps their Discord roles and channel access synchronized with their in-game membership.

Less manual Discord administration. Better organized communities. Permissions that follow your Towny server.

Downloads & Minecraft Compatibility

TownyDiscordChat supports 14 Minecraft versions, from 1.16.5 through 26.3!

The primary Hangar download currently targets Minecraft 26.3, but separately compiled builds are available for all other supported versions.

Please download the JAR matching your server's exact Minecraft version.

Download TownyDiscordChat 1.1.1

Minecraft Version · Download
26.3 · Download JAR
26.2 · Download JAR
26.1.2 · Download JAR
1.21.11 · Download JAR
1.21.10 · Download JAR
1.21.8 · Download JAR
1.21.4 · Download JAR
1.21.1 · Download JAR
1.20.6 · Download JAR
1.20.1 · Download JAR
1.19.4 · Download JAR
1.18.2 · Download JAR
1.17.1 · Download JAR
1.16.5 · Download JAR

View all releases and downloads on GitHub

The links above are pinned to version 1.1.1 (Pre-Release). For newer builds, check the GitHub Releases page.

Java and Server Requirements

Minecraft Versions · Server Software · Java
1.16.5, 1.17.1, 1.18.2 · Spigot / Paper / Purpur · Server-dependent
1.19.4, 1.20.1, 1.20.6 · Paper / Purpur · Server-dependent
1.21.1 – 1.21.11 (listed builds) · Paper / Purpur · 21+
26.1.2, 26.2, 26.3 · Paper / Purpur · 25+

Important compatibility notes:

• Every JAR is compiled against its corresponding Minecraft server API.
• Minecraft 26.3 requires a compatible Towny pre-release.
• Folia is not currently supported.
• Spigot/CraftBukkit with Towny 0.102+ is not supported.
• Minecraft 26.1.0 and 26.1.1 are excluded; use 26.1.2 for the 26.1 series.
• Compatibility is build-verified, not a guarantee of successful deployment on every server configuration.

For the complete compatibility matrix, including Towny and DiscordSRV versions, see the Compatibility Documentation.

Why TownyDiscordChat?

Running a Minecraft Towny server often means managing an equally complex Discord community.

Every time someone establishes a town, joins a nation, changes their membership, or renames a settlement, administrators may need to manually update Discord roles, channels, and permissions.

On larger servers, this becomes difficult to maintain. Outdated permissions can even allow former residents to access private conversations.

TownyDiscordChat solves this problem by using Towny as the source of truth for your Discord community structure.

Once configured, the plugin manages your town and nation Discord resources automatically.

What TownyDiscordChat Does NOT Do

TownyDiscordChat does not relay Minecraft town or nation chat messages to Discord, or Discord messages back into Minecraft.

This is not a replacement for DiscordSRV's general chat bridging functionality.

Instead, TownyDiscordChat focuses on Discord role management, private channel organization, membership synchronization, and access control.

Features

Automatic Discord Role Management

• Create and maintain separate Discord roles for towns and nations.
• Automatically assign roles to linked Discord accounts based on Towny membership.
• Remove outdated roles when players leave or change communities.
• Synchronize membership changes without requiring administrators to manually update Discord.
• Rename managed roles when towns or nations are renamed.

Private Town and Nation Channels

Give each community its own private space in Discord.

• Automatically create private text channels for towns and nations.
• Automatically create voice channels.
• Organize channels into configurable Discord categories.
• Restrict channel access to members with the appropriate town or nation roles.
• Preserve existing managed channel identities when settlements are renamed.
• Carefully validate permissions before creating, adopting, or modifying resources.

DiscordSRV Account Linking

TownyDiscordChat uses DiscordSRV's existing Minecraft-to-Discord account linking system.

• No separate registration or verification system.
• Players can check their linking status using /tdc status.
• Players can initiate account linking using /tdc link.
• Optional in-game reminders encourage eligible players to link their accounts.
• Changes to linked accounts automatically trigger membership reconciliation.

Reliable Synchronization

TownyDiscordChat includes a database-backed synchronization system designed to keep Discord access aligned with Minecraft membership.

• Persistent job queue that survives server restarts.
• Automatic retries and recovery for interrupted operations.
• Prioritization of access revocations over new grants.
• Protection against duplicate or ambiguous Discord resources.
• Safe handling of town and nation renames.
• Scheduled reconciliation and administrative audits.
• Discord API rate-limit handling through DiscordSRV/JDA.

SQLite and MySQL Support

No external database server is required.

TownyDiscordChat uses SQLite by default, automatically creating a local database to track synchronization operations and identities.

MySQL is also supported for administrators who prefer an external database.

Existing SQLite data can be migrated to MySQL using the built-in migration process.

Administrative Tools and Logging

• Check synchronization status and pending operations.
• Request Discord membership audits.
• Retry failed operations after resolving permission or configuration problems.
• View detailed resource creation, adoption, rename, deletion, grant, and revocation activity in the Minecraft console.
• Optionally publish activity and administrative warnings to an existing private Discord log channel.
• Prevent unsafe synchronization when configuration or Discord permissions are invalid.

How It Works

Imagine your Minecraft server has a town called Oakvale, belonging to the nation Northlands.

1. A Town Is Created

TownyDiscordChat creates or adopts the necessary Discord resources, such as:

• town-Oakvale — Discord role for town residents.
• nation-Northlands — Discord role for nation members.
• Private text and voice channels for each community.

2. A Player Joins Oakvale

Once that player links their Minecraft account with Discord through DiscordSRV, TownyDiscordChat grants their appropriate town and nation roles.

3. The Player Accesses Discord

The player can now participate in Oakvale's private Discord channels and their nation's shared channels.

4. The Player Changes Towns

TownyDiscordChat updates their Discord membership, removing access to channels they are no longer entitled to and granting access to their new community.

All without manually editing Discord roles or channel permissions.

Requirements

TownyDiscordChat requires the following plugins:

• Towny Advanced — Manages Minecraft towns, nations, and player membership.
• DiscordSRV — Connects your Minecraft server to Discord and provides account linking.

You must also configure a Discord bot with sufficient permissions to manage the Discord roles and channels used by TownyDiscordChat.

Important: Towny and DiscordSRV must be installed separately. They are not included in the TownyDiscordChat JAR.

Installation

1. Install the Dependencies

Install and configure Towny Advanced and DiscordSRV on your Minecraft server.

Follow the DiscordSRV setup guide to configure your Discord bot and connect it to your server.

2. Configure Discord Permissions

Ensure your Discord bot has the permissions necessary to manage roles and channels, including:

• Manage Roles
• Manage Channels
• View Channels
• Send Messages in the configured log channel, if enabled

Place the bot's highest role above the Towny and nation roles that it will manage.

Enable the Server Members Intent for full membership auditing.

3. Download TownyDiscordChat

Choose the correct JAR for your Minecraft version from the [download table above](#downloads--minecraft-compatibility) or the GitHub Releases page.

Place the JAR inside your Minecraft server's plugins/ directory.

Do not install the release ZIP itself. The ZIP provides the matching JAR along with configuration examples and documentation.

4. Configure the Plugin

For a new installation, use the config.example.yml provided in the matching GitHub release ZIP as the basis for:

plugins/TownyDiscordChat/config.yml

Configure your preferred Discord category names, role settings, storage options, and activity logging.

Recommendation: Perform your initial setup using a test Discord server. The plugin can create, rename, and delete Discord resources and modify channel access permissions.

5. Start and Verify

Start your Minecraft server and inspect the console for configuration and Discord permission validation.

Use the following administrative commands:

/tdcqueue status
/tdcqueue audit

The plugin will automatically synchronize eligible Towny resources and linked members once its configuration and Discord environment have been validated.

Updating From an Older Version

TownyDiscordChat supports an optional configuration migration using config.yml.bak.

To upgrade:

1. Stop your Minecraft server.
2. Back up your existing plugin configuration and database.
3. Rename your existing config.yml to config.yml.bak in the same plugin directory.
4. Install the new TownyDiscordChat JAR.
5. Start the server.

TownyDiscordChat will generate a fresh configuration using the current defaults and import compatible settings from your backup.

Important: The first migration