Towny3D

Towny3D

A high-performance 3D land protection plugin for Hytale servers featuring town/nation management, plot claims, PvP control, and advanced permission systems with Kotlin coroutines and spatial indexing.

Status: Alpha - This plugin is experimental and under active development. It has been ported from the Spigot API to the Hytale API with extensive use of Claude Code, relying primarily on decompiled source code of the Hytale server.

Dependencies

Required:

Cassaforte - Service registry plugin for economy, permissions, and chat integration

Any economy plugin compatible with cassaforte, like SimpleEconomy or TheEconomy

Towny3D requires Cassaforte to be installed and loaded first. Cassaforte provides the service registry that Towny3D uses for economy integration (will fall back to internal economy if none available)

Key Features

3D Claiming System

Towny3D introduces true 3D land claims - you can have multiple plots in the same chunk at different vertical levels! Simply select the lower and upper points of your desired plot area using the claim stick, then run the claim command.

Vertical granularity: Claim specific Y-axis ranges rather than entire chunks

Spatial indexing: Fast region lookups with optimized spatial cache

Claim Stick: Use /claim gcs (get claim stick) to set plot boundaries

Implemented Features

Town Management

/town create <townName> - Create a new town

/town delete - Disband your town

/town info [townName] - View town information

/town list - List all towns

/town join <townName> - Join an open town

/town leave - Leave your current town

Nation Management

/nation create <nationName> - Create a new nation

/nation delete - Disband your nation

/nation info [nationName] - View nation information

/nation list - List all nations

/nation join <nationName> - Join an open nation

/nation leave - Leave your current nation

/nation invite <townName> - Invite a town to your nation

/nation kick <townName> - Kick a town from your nation

Plot Management

/plot claim - Claim the plot you're standing in

/plot unclaim - Unclaim the plot you're standing in

/plot forsale <price> (alias: /plot fs) - Put a plot up for sale

/plot notforsale (alias: /plot nfs) - Remove plot from market

/plot info - View plot information

/plot name <name> - Name your plot

/plot showBorders (alias: /plot sb) - Show plot borders visually

/plot hideBorders (alias: /plot hb) - Hide plot borders

Claiming Commands

/claim gcs (get claim stick) - Get the item to set lower and upper plot points

/claim [chunk] - Claim land at selected 3D region

/claim auto - Automatically claim adjacent land

/claim unclaim - Unclaim town land

Selection Commands (WorldEdit-style)

/p1 - Set first position (lower corner) for region selection

/p2 - Set second position (upper corner) for region selection

/pos1 - Alias for /p1

/pos2 - Alias for /p2

Town Toggles

/toggle pvp [on/off] - Toggle PvP in town

/toggle public [on/off] - Toggle public status

/toggle explosions [on/off] - Toggle explosion protection

/toggle open [on/off] - Toggle open joining

Chat System

/tc <message> (alias: /townchat) - Send message to town chat

/nc <message> (alias: /nationchat) - Send message to nation chat

/g <message> (alias: /globalchat) - Send message to global chat

/chat town|nation|global - Switch default chat mode

Economy

/balance (alias: /bal) - Check your balance (only with internal economy)

/resident balance - Check resident balance

/town balance - Check town bank balance

/nation balance - Check nation bank balance

/eco give <player> <amount> - Give money to player

/eco take <player> <amount> - Take money from player

/eco set <player> <amount> - Set player balance

/eco balance <player> - Check player balance

Note: Economy commands are only available when using Towny3D's internal economy. If an external economy (like Cassaforte's built-in or another plugin) is available, use that economy's commands instead. Towny3D automatically falls back to internal economy if no external economy is available.

Upkeep and Taxation

Towny3D features a comprehensive upkeep and taxation system to maintain economic balance and encourage active participation.

Tax Types:

Town Upkeep - Periodic cost towns pay to the server (configurable, defaults to disabled)

Nation Upkeep - Periodic cost nations pay to the server (configurable, defaults to disabled)

Nation Taxes - Nations can tax member towns (flat amount or percentage of town balance)

Town Taxes - Towns can tax residents (flat amount or percentage of resident balance)

Plot Taxes - Towns can set taxes on individual plots (flat amount or percentage)

Tax Commands:

/town tax <flat|percent> <amount> - Set resident tax for your town

/town tax clear - Clear resident tax

/town tax info - View town tax settings

/nation tax <flat|percent> <amount> - Set tax on member towns

/nation tax clear - Clear nation tax

/nation tax info - View nation tax settings

/nation debt [town] - View town debts to nation

/plot tax <flat|percent> <amount> - Set tax for current plot

/plot tax clear - Clear plot tax

/plot tax info - View plot tax info

/tax - Show your personal tax burden

/tax town <name> - View town tax info

/tax nation <name> - View nation tax info

Admin Tax Commands:

/ta collecttaxes - Force immediate tax collection

/ta nexttax - Show when next collection occurs

/ta reclaim <town|nation> <name> - Reclaim a ruined entity

/ta ruinate <town|nation> <name> - Force entity into ruined state

/ta settaxtime <HH:mm> - Change tax collection time

/ta toggle upkeep - Enable/disable upkeep system

Consequences:

Town/Nation can't pay upkeep → Falls to ruins (can be reclaimed for a fee)

Resident can't pay plot tax → Loses plot ownership

Resident can't pay resident tax → Payment skipped (no debt)

Town can't pay nation tax → Goes into debt, blocked from leaving nation

Invitations

/accept - Accept pending town/nation invitation

/decline - Decline pending invitation

Admin Commands (/townyadmin)

/ta reload - Reload plugin configuration

/ta save - Force save all data

/ta stats - View plugin statistics

/ta unclaim - Admin force unclaim

/ta reset - Reset plugin data

Resident Commands

/res (alias: /resident) - Resident command root

/res info [player] - View resident information

/res list - List all residents

/balance - Check balance

Protection Systems

Entity Protection: Control entity spawning and interactions

Explosion Protection: Prevent damage from explosions

Player Interactions: Control block placement, breaking, and item usage

PvP Control: Fine-grained PvP toggle per region

Chunk Enter Notifications: Display town/region info on entry

Planned Features (Not Yet Implemented)

Town Commands

/town mayor - Mayor management submenu

/town addAssistant <playerName> - Add town assistant

/town removeAssistant <playerName> - Remove town assistant

/town setHome - Set town spawn point

/town spawn - Teleport to town spawn

/town online - List online residents

/town here - Show info for town you're standing in

/town kick <playerName> - Kick resident from town

/town deposit <amount> - Deposit to town bank

/town withdraw <amount> - Withdraw from town bank

/town set perm <permGroup> <permType> <value> - Set town permissions

Plot Commands

/plot toggle <flag> [on/off] - Toggle plot flags (pvp, explosion, fire, mobs)

/plot set perm <permGroup> <permType> <value> - Set plot permissions

/plot set embassy - Mark plot as embassy

/plot reset - Reset plot to default settings

Town Permission & Flag System

The flag system is partially implemented for plot toggling. Permission groups are planned.

Implemented Flags (via /plot toggle):

pvp - Player vs Player combat

explosion - Explosion damage

fire - Fire spread and damage

Planned Flags:

friendly_mobs_spawn - Friendly mob spawning

hostile_mobs_spawn - Hostile mob spawning

Planned Permissions (for groups: res/ally/gen):

pvp - Player vs Player combat

inventory - Inventory access

interact - Block interaction

build - Place blocks

destroy - Break blocks

drop - Drop items

pick - Pick up items

move - Movement

Admin Features

/townyadmin chat spy - Spy on town/nation chats

Permissions

All Towny3D permissions use the towny3d. prefix. Permissions are checked automatically by the Hytale server's permission system.

Default Permissions

Permission Node Description Default

towny3d.admin Full admin access to all Towny3D commands OP only

towny3d.* Wildcard for all Towny3D permissions OP only

Command Permissions

General Commands

Permission Description

towny3d.balance Check account balance

towny3d.resident Base resident command access

towny3d.resident.info View resident information

towny3d.resident.list List all residents

towny3d.resident.balance Check resident balance

Town Commands (/town, /t)

Permission Description

towny3d.town Base town command access

towny3d.town.create Create a new town

towny3d.town.delete Delete your town

towny3d.town.join Join a town

towny3d.town.leave Leave your town

towny3d.town.list List all towns

towny3d.town.info View town information

towny3d.town.claim Claim land for town

towny3d.town.unclaim Unclaim town land

towny3d.town.set Change town settings

towny3d.town.toggle Toggle town flags

towny3d.town.deposit Deposit to town bank

towny3d.town.withdraw Withdraw from town bank

towny3d.town.kick Kick residents from town

towny3d.town.invite Invite players to town

towny3d.town.add_assistant Promote resident to assistant

towny3d.town.remove_assistant Demote assistant to resident

towny3d.town.spawn Teleport to town spawn

towny3d.town.set_home Set town spawn location

towny3d.town.online List online town members

towny3d.town.here Show town at current location

Nation Commands (/nation)

Permission Description

towny3d.nation Base nation command access

towny3d.nation.create Create a new nation

towny3d.nation.delete Delete your nation

towny3d.nation.join Join a nation with your town

towny3d.nation.leave Leave your nation

towny3d.nation.list List all nations

towny3d.nation.info View nation information

towny3d.nation.kick Kick town from nation

towny3d.nation.invite Invite town to nation

Plot Commands (/plot)

Permission Description

towny3d.plot Base plot command access

towny3d.plot.claim Claim a plot

towny3d.plot.unclaim Unclaim a plot

towny3d.plot.forsale Put plot up for sale

towny3d.plot.notforsale Remove plot from market

towny3d.plot.set Set plot permissions (collection)

towny3d.plot.set.perm Set plot permissions

towny3d.plot.set.reset Reset plot to default settings

towny3d.plot.toggle Toggle plot flags

towny3d.plot.name Name a plot

towny3d.plot.show_borders Show plot boundary markers

towny3d.plot.hide_borders Hide plot boundary markers

towny3d.plot.info View plot information

Claim Commands (/claim)

Permission Description

towny3d.claim Base claim command access

towny3d.claim.stick Get claim stick tool

towny3d.claim.auto Toggle automatic claiming

towny3d.claim.unclaim Unclaim land at position

towny3d.claim.land Manual land claim

Chat Commands (/chat, /tc, /nc, /g)

Permission Description

towny3d.chat Base chat command access

towny3d.chat.town Use town chat channel

towny3d.chat.nation Use nation chat channel

towny3d.chat.global Switch to global chat

Invite Commands (/invite, /accept, /decline)

Permission Description

towny3d.invite Base invite command access

towny3d.invite.accept Accept pending invitations

towny3d.invite.decline Decline pending invitations

towny3d.invite.list List pending invitations

towny3d.invite.send Send invitations

Toggle Commands (/toggle)

Permission Description

towny3d.toggle Base toggle command access

towny3d.toggle.pvp Toggle PvP protection

towny3d.toggle.explosions Toggle explosion protection

towny3d.toggle.public Toggle public access

towny3d.toggle.open Toggle open status

Admin Commands (/ta)

Permission Description

towny3d.admin All admin commands (use this for full admin access)

towny3d.admin.reload Reload plugin configuration

towny3d.admin.save Force save all data

towny3d.admin.stats View server statistics

towny3d.admin.unclaim Admin force unclaim

towny3d.admin.reset Reset town/player data

towny3d.admin.chat Admin chat options

towny3d.admin.spy Spy on chat channels

Economy Admin Commands (/eco)

Permission Description

towny3d.eco Base economy admin access

towny3d.eco.give Give money to player

towny3d.eco.take Take money from player

towny3d.eco.set Set player balance

towny3d.eco.balance Check player balance

Example Permission Setup

PermissionsBukkit / Default

# Give players basic town access towny3d.town: true towny3d.town.info: true towny3d.town.list: true towny3d.town.join: true towny3d.town.leave: true towny3d.resident: true towny3d.resident.info: true towny3d.balance: true

# Give mayors additional permissions towny3d.town.create: true towny3d.town.claim: true towny3d.town.kick: true towny3d.town.invite: true towny3d.plot: true towny3d.plot.claim: true towny3d.toggle: true

# Give admins full access towny3d.admin: true LuckPerms

# Default player group lp group default permission set towny3d.town true lp group default permission set towny3d.town.info true lp group default permission set towny3d.town.list true lp group default permission set towny3d.town.join true lp group default permission set towny3d.resident true lp group default permission set towny3d.balance true

# Mayor rank lp group mayor permission set towny3d.town.create true lp group mayor permission set towny3d.town.claim true lp group mayor permission set towny3d.plot true lp group mayor permission set towny3d.toggle true

# Admin rank lp group admin permission set towny3d.* true UltraPermissions

groups: default: permissions: - towny3d.town - towny3d.town.info - towny3d.town.list - towny3d.town.join - towny3d.resident - towny3d.balance mayor: permissions: - towny3d.town.* - towny3d.plot.* - towny3d.toggle.* admin: permissions: - towny3d.* Architecture

Performance Optimizations

Kotlin Coroutines: Asynchronous operations for database I/O and network calls

Caffeine Caching: High-performance caching for towns, nations, residents, and regions

Spatial Indexing: Efficient 3D region lookups with spatial cache

Batch Storage: Periodic batch writes to reduce I/O operations

Storage

JSON-based storage backend

Automatic saving with configurable intervals

Batch writer for efficient writes

Development Status

This is an alpha release. Many core features work, but expect bugs and missing functionality. The plugin is being developed without official Hytale documentation, relying on decompiled server code.

Known Limitations

API may change significantly as Hytale server updates

Some features from original Towny not yet ported

Testing limited by available server versions

Contributing

This is a personal project developed to bring Towny-like functionality to Hytale. Contributions welcome once the plugin stabilizes.

Credits

Inspired by Towny3D for Minecraft/Spigot of which I am the author

Ported to Hytale API through reverse engineering