Towny: complete guide to running an SMP with cities and nations

Towny is a plugin about founding cities, joining them into nations and protecting territory from outsiders. Below: how it differs from Factions, how to set it up on Paper 1.20-1.21, which commands players actually need, what lives in townyperms.yml, and how to bolt on wars, web maps and LuckPerms.

What Towny Advanced is and why this fork

The original Towny was written by ElgarL back in 2009, but the actively maintained branch since 2014 is Towny Advanced under LlmDl. That is what people mean today when they say "Towny". The old forks are long dead, no point even looking for them.

The idea is simple: a player picks a chunk, makes it the center of their town (the homeblock), then claims neighbouring chunks for in-game money. Inside the town only residents can build and break blocks. Several towns can join into a nation, the nation has a capital, allies and enemies.

How it differs from Factions: Factions is built around PvP wars, forceful chunk grabs, constant conflict. Towny is calmer, focused on economy, taxes, building cities. Towns are not taken by force out of the box, wars need an add-on like SiegeWar. If your server is about peaceful building and trade with a touch of politics, pick Towny. For a pure raid server, look at Factions or Lands.

Another comparison: Lands is a modern alternative with table-style UI, easier for newcomers. Towny wins on maturity, a huge add-on ecosystem and deeper permission control.

Installation on Paper 1.20-1.21

Towny officially supports Paper, Spigot and Purpur. CraftBukkit works too, but no one uses it anymore. Folia is not supported because of the plugin's internal architecture (see FAQ).

What you need:

• Paper 1.20.x or 1.21.x (a recent build from paper.io)
• Vault as the economy bridge, without it taxes and town pricing won't work
• Any economy plugin: EssentialsX Economy, CMI, TheNewEconomy
• Optional: LuckPerms for permissions, Dynmap or BlueMap for the web map

Basic install:

cd /home/mc/server/plugins
wget https://github.com/TownyAdvanced/Towny/releases/latest/download/Towny.jar
wget https://github.com/MilkBowl/Vault/releases/latest/download/Vault.jar
# EssentialsX and EssentialsXChat - from https://essentialsx.net

After the first start Towny creates the plugins/Towny/ folder with all configs. Don't dive in editing right away, let it boot at least once so files generate fully.

Player commands: the basics

The minimal set every player will actually use:

/town new <name>              found a town (current chunk = homeblock)
/town claim                   add a chunk to your town
/town unclaim                 release a chunk
/town invite <player>         invite a resident
/town kick <player>           remove a resident
/town set mayor <player>      transfer mayorship
/town deposit <amount>        put money into the town bank
/town withdraw <amount>       withdraw (mayor only)
/town spawn                   teleport to the town's homeblock
/plot claim                   buy a plot inside the town (if for sale)
/plot forsale <price>         list your plot for sale
/resident friend add <player> let a friend build on your plot

/nation new <name>            found a nation (must be mayor)
/nation add <town>            add a town to the nation
/nation ally add <nation>     ally with another nation
/nation enemy add <nation>    declare an enemy
/nation king <player>         transfer kingship

Players usually only need /town, /plot, /resident. Nation commands matter to mayors and kings.

Practical tip: at spawn, post a sign with three commands. /town new MyCity, /town claim, /town spawn. That covers 80% of new players figuring it out alone.

townyperms.yml: resident, mayor and king rights

The file plugins/Towny/townyperms.yml controls what a player can do depending on their role. This is the single most important file for fine tuning. Structure:

nomad:
  - towny.chat.global
  - towny.command.town.new
  - towny.command.resident

resident:
  - towny.chat.town
  - towny.chat.nation
  - towny.command.plot.claim
  - towny.command.plot.forsale

towns:
  default:
    - towny.command.town.deposit
    - towny.command.town.spawn
  mayor:
    - towny.command.town.claim
    - towny.command.town.unclaim
    - towny.command.town.invite
    - towny.command.town.kick
    - towny.command.town.set
    - towny.command.town.withdraw
    - towny.command.town.toggle
  ranks:
    assistant:
      - towny.command.town.claim
      - towny.command.town.invite
    builder:
      - towny.command.plot.claim
    sheriff:
      - towny.command.town.kick

nations:
  default:
    - towny.command.nation.spawn
  king:
    - towny.command.nation.add
    - towny.command.nation.king
    - towny.command.nation.ally
    - towny.command.nation.enemy
  ranks:
    chancellor:
      - towny.command.nation.add
    diplomat:
      - towny.command.nation.ally

The logic: nomad is a player without a town, resident is anyone in any town, towns.default is a resident inside their own town, towns.mayor is the mayor, towns.ranks.* are custom ranks the mayor hands out via /town rank add <player> <rank>. Nations work the same way.

Assistant and sheriff ranks are very useful: when the mayor goes on holiday, handing over mayorship feels risky, but an assistant with claim rights can keep growing the town without any chance of stealing the treasury.

config.yml: prices, taxes, limits

The main config sits at plugins/Towny/settings/config.yml. The file is huge, but only about fifteen knobs really matter on day one:

economy:
  price_new_town: 250.0
  price_new_nation: 1000.0
  price_claim_townblock: 25.0
  price_outpost: 100.0
  daily_taxes:
    enabled: true
    max_tax_amount_town: 1000.0
    max_tax_percent_town: 25.0

town:
  max_townblocks: 16
  townblocks_claimed_at_a_time: 1
  ratio_townblocks_per_resident: 8
  bonus_townblock_amount_unlimited: false
  max_residents_per_town: 0
  max_outposts: 3

nation:
  max_towns_per_nation: 0
  max_outposts: 5

global_town_settings:
  pvp:
    default: false
  fire:
    default: false
  explosions:
    default: false
  mobs:
    default: false

ratio_townblocks_per_resident: 8 means one resident grants the town 8 chunks. A 5-person town can claim up to 40 chunks (plus max_townblocks as the floor). This is a natural growth limiter, without it one or two players will swallow half the map.

daily_taxes.enabled: true plus a town tax forces the mayor to keep an eye on the treasury. If the bank runs dry Towny starts unclaiming chunks automatically (see town.delete_town_block_when_unable_to_pay_tax).

The global PvP, fire, explosions and mobs flags are defaults for new towns. The mayor can flip them later via /town toggle pvp and so on, if you allow that in townyperms.yml.

Economy: taxes, plot rent, nation bank

Towny supports three tax types:

• Town tax - the nation deducts daily from a town. Paid from the town bank, not residents' pockets.
• Resident tax - the town charges every resident. Residents who can't pay get evicted.
• Plot rent - a plot owner charges friends they let build there.

These are toggled in config.yml under economy.daily_taxes. The trigger time is server-time midnight by default, controlled by new_day_time.

Plots inside towns can be sold and rented. Mayor or owner runs /plot forsale 500, any resident buys via /plot claim. The owner can then set rent:

/plot set rent 50            50 coins per day
/plot fr                     stop renting (forrent)

The nation bank fills up from town taxes. The king spends it on wars, allies, banners, whatever you wire up via add-ons.

PvP, mobs, fire, explosions

Town flags toggle via /town toggle <flag>:

/town toggle pvp
/town toggle mobs
/town toggle fire
/town toggle explosion
/town toggle public
/town toggle taxpercent

Global limits sit in config.yml under global_town_settings.world_settings:

unclaimed:
  unclaimed_zone_build: false
  unclaimed_zone_destroy: false
  unclaimed_zone_switch: false
  unclaimed_zone_item_use: false
  unclaimed_zone_mobs: true
  unclaimed_zone_ignore:
    - GRASS
    - LONG_GRASS
    - DEAD_BUSH

These are the rules for wilderness, the unclaimed land outside towns. By default I set build/destroy/switch to false and mobs to true. That way nobody can grief under "no claim here" cover, but mobs spawn normally so players can level.

unclaimed_zone_ignore lets players cut grass and dead bushes outside towns. Otherwise running through a hostile savanna gets dull fast.

Wars: SiegeWar and Flagwar

Stock Towny does not let you take someone else's town. For a PvP server you install one of two add-ons.

SiegeWar - modern, actively developed. The attacking nation places a banner near the target town (siege banner), a timer starts. Residents defend, attackers hold the point. Outcome: the town flips to the attacker, pays reparations, or defenders burn the banner. Realistic politics.

/swa <name>     start a siege
/sw siege       siege status

SiegeWar has its own config in plugins/SiegeWar/. Key knobs: siege duration, minimum distance between banners, requirement to be in a nation to attack.

Flagwar - old school. Attacker places a flag on the victim's chunk, a countdown runs, defenders break the flag or not. Simpler but cruder, individual chunks fight, not whole towns. Good for short fast PvP without big politics.

For an SMP focused on roleplay and nations pick SiegeWar. For hard PvP, Flagwar.

Web map: Dynmap-Towny and BlueMap-Towny

To show towns on a web map you install Dynmap or BlueMap plus the matching bridge plugin. Without bridges the map exists but has no town borders.

# Dynmap
wget https://dev.bukkit.org/projects/dynmap/files/latest -O Dynmap.jar
wget https://github.com/TownyAdvanced/Dynmap-Towny/releases/latest/download/Dynmap-Towny.jar

# Or BlueMap (looks much better, renders 3D)
# bluemap.jar + bluemap-towny.jar

After a restart towns appear as coloured polygons with names. Colours are configured in plugins/Dynmap-Towny/Dynmap-Towny.yml. You can paint nation capitals one colour, regular towns another, enemies red.

BlueMap looks prettier but eats CPU during the initial render. Dynmap is lighter and runs fine on weak hardware. For a busy production server with a large map I usually pick Dynmap, for a flashy SMP demo BlueMap.

LuckPerms + Towny

Towny has its own ranks inside towns and nations (townyperms.yml), but the basic permission nodes (towny.command.town.new, towny.chat.global, etc) are handed out by a normal permissions plugin. The standard is LuckPerms.

Minimal setup:

lp group default permission set towny.chat.global true
lp group default permission set towny.command.town.new true
lp group default permission set towny.command.resident true
lp group default permission set towny.command.plot.claim true
lp group default permission set towny.command.plot.forsale true

# VIP group: more plots and outposts
lp group vip permission set towny.command.town.new true
lp group vip meta set bonus_townblocks 25

Everything inside the town and nation comes from townyperms.yml. Don't duplicate the same nodes in LuckPerms or the mayor will lose control over their own residents.

Anti-grief: Towny + WorldGuard

Inside claims WorldGuard is not needed. Towny already blocks block place/break, chest access, doors and pressure plates. You only get conflicts when both plugins manage the same area.

Where WorldGuard still earns its keep:

• spawn (flags pvp deny, block-break deny, mob-spawning deny)
• arenas, event zones
• TNT/end-crystal limits in wilderness so people don't dupe terrain into oblivion

The pattern is: WorldGuard at spawn and special zones, Towny everywhere else. No overlapping regions.

FAQ

Towny vs Factions vs Lands - which to pick

Factions is a PvP raid server, constant wars and territory grabs. Lands is the modern beginner-friendly option, simple UI, less depth. Towny is the middle path: economy, taxes, nations, politics, optional wars via SiegeWar. If your server is about long-term play and cities that last for months, pick Towny. For fists and fast levelling, Factions.

Can I run Towny on a cracked server

Yes. Towny is not tied to Mojang UUID auth. On a cracked server with AuthMe or nLogin Towny works fine, residents are stored by name. One catch: when a player changes their name they lose town access because the old name is in the database. On a premium server this is solved with UUID mode in database.yml.

How do I cap town size

Three knobs in config.yml:

• town.max_townblocks - hard ceiling on chunks per town
• town.ratio_townblocks_per_resident - chunks granted per resident
• town.max_residents_per_town - resident cap per town (0 = no limit)

On SMP I run max_townblocks: 64, ratio: 8, max_residents: 0. That gives an 8-person town exactly 64 chunks, a balanced ceiling that doesn't eat the map.

Is Towny compatible with Folia

As of 1.21, no. Folia needs region-local execution but Towny touches the whole world from a single thread, especially during daily tax processing and chunk unclaiming. LlmDl has not announced a Folia port. If you need Folia, look at Lands, which has announced support.

Can I disable city capture entirely

Yes. Don't install SiegeWar or Flagwar and stock Towny gives nobody a way to take someone else's town. The only ways to lose a town: the mayor runs /town delete, or the town fails to pay nation tax and gets dissolved, or it fails to pay chunk upkeep and chunks unclaim one a day. Pure economic mechanics.

What is an outpost and why do I need it

An outpost is a remote chunk of a town that doesn't touch the homeblock. Created with /town claim outpost, costs more than a normal chunk (price_outpost). Useful for a remote mine, a Nether portal, a farm. Outpost cap is town.max_outposts.

How do I set the town spawn

The mayor stands on the desired chunk (must be inside the town's claims) and runs /town set spawn. After that any resident hits /town spawn to teleport. Cooldown and cost live under the spawning section in config.yml.

What's next

A starter checklist after install:

• verify Vault sees the economy: run /vault-info or /eco balance from a test account
• walk through townyperms.yml and tune ranks for your scenario right away, don't ship the default
• enable daily_taxes and pick max_townblocks for your map size, otherwise in a month you'll see 500-chunk megacities
• decide on wars at launch: SiegeWar is a one-way door, players adapt to the politics quickly
• for a public server lock down wilderness via the unclaimed_zone_* flags, otherwise the terrain gets carpet-bombed in a week

From here you either go addon-heavy (SiegeWar, Towny Camps for temporary camps, Towny Histories for logs) or dig into townyperms.yml for tight permission tuning. The base setup is enough for a big SMP launch, the rest grows with the player count.