TownyDiscordChat

Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!

Connect Towny with Discord through town and nation channels, role synchronization, and permission-based access.

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 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:

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

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

Important: The first migration startup runs in safe mode and does not perform Discord synchronization.

Review the new configuration, then restart the server to activate synchronization.

Your original .bak file remains untouched.

Read the complete upgrade instructions before upgrading a production server.

Commands and Permissions

Player Commands

Command	Description
`/tdc`	Display plugin information and linking status.
`/tdc status`	Check Towny membership and Discord linking status.
`/tdc link`	Start the DiscordSRV account-linking process.

Administrative Commands

Command	Description
`/tdcqueue status`	View synchronization queue status.
`/tdcqueue audit`	Request a Discord membership audit.
`/tdcqueue retry-dead`	Retry failed queue operations.
`/tdc Check ...`	Request targeted or broader resource reconciliation.

Administrative permission: TownyDiscordChat.Admin

Player linking also uses DiscordSRV's existing permissions.

For detailed command usage and legacy permission nodes, see the GitHub documentation.

Security and Privacy

Discord channel privacy is an important part of TownyDiscordChat's design.

The plugin validates managed categories and channel permissions before performing synchronization operations.

Important safeguards include:

Verification that private channels deny public @everyone access.
Conservative adoption of existing Discord roles and channels.
Rejection of ambiguous or unsafe managed resources.
Validation of Discord role permissions to avoid adopting roles with elevated administrative capabilities.
Preservation of existing role permissions when safely adopting roles.
Startup safe mode when critical configuration or permissions are invalid.

Note: Changes to Discord access are subject to bot connectivity and Discord API availability. Failed revocations should be investigated promptly.

Troubleshooting

Players Cannot Access Their Town Channels

Verify that they belong to a Towny town and have linked their Discord account.

Check:

/tdc status
/tdcqueue status

Queue operations may still be pending or may have failed.

The Bot Cannot Create or Assign Roles

Verify the bot's Manage Roles permission and ensure its role is positioned above the managed Towny roles in Discord.

Also verify Manage Channels permission and category-level access.

The Plugin Starts in Safe Mode

Inspect the Minecraft console for:

Configuration validation errors.
Unsafe Discord categories.
Missing bot permissions.
Storage connection problems.
Incompatible plugin versions.

Resolve the reported issue and restart the server.

Discord Activity Logs Are Missing

Verify that logging is enabled, the configured private log channel exists, and the bot can view and send messages in it.

The plugin does not automatically create a public logging channel.

For additional help, see the GitHub README.

Open Source and Community

TownyDiscordChat is open-source software licensed under the GNU General Public License v3.0.

Contributions, bug reports, and suggestions are welcome.

Build a better-connected Towny community.

Let TownyDiscordChat manage your Discord community structure so your players can focus on their towns, nations, and communities.

TownyDiscordChat