Skip to content

How Towny Works

Jump to bottom Edit New page
LlmDl edited this page Oct 6, 2024 · 72 revisions

Use this page to learn how Towny works, how various settings affect the game play, what you can do to customize Towny to your liking.

The Hierarchy

Nomads

Nomads are simply players who are not part of any town. They are landless and their permission nodes are configurable via TownyPerms.yml. Nomads can purchase Embassy plots if they have been given towny.command.plot.claim in the Townyperms.yml. Nomads automatically receive the towny.townless permission node.

Residents

Every person who joins your server can become a resident of a town, (by default they are given the towny.town.resident permission node in townyperms.yml's nomad section.) Residents have their own command /resident which used by itself outputs a Resident Status Screen, displaying Money, Town, Plots owned and Friends. Residents can join towns or choose to start a town of their own.

Residents can also be put into one town automatically when they join the server for the first time by setting default_town_name: '' in the config.yml.

Residents who join towns can claim plots that the Mayor of the town has set for sale. When a resident owns 1 or more plots, they will see a new line on their Resident Screen, showing plots owned and a default perm line showing the plot perms given on all plots that resident owns, (which haven't had a custom plot line set.)

Residents who have joined a town have their permission nodes configurable via TownyPerms.yml in the towns.default section.

Towns

Click here for Major Graft's Towns & Nations Video A town is a collection of residents (or just one resident) with one resident as the mayor. A town also has a bank which the mayor can withdraw from. A mayor can also have assistants who have the same or similar powers as him/herself. Towns can have taxes that will be taken at the end of each day interval.

Towns usually grow outwards from their home block, the townblock the mayor stood in during town creation. Townblocks need to be claimed beside other townblocks, unless the mayor claims an outpost in the wilderness using /t claim outpost. Towns can be limited to a number of residents using the config option global_town_settings.max_residents_per_town, by default this is not limited. All of the towns on a server can be seen in a list using /town list.

As of Towny 0.95.1.0 it is possible to store MetaData on a town, see here for details.

As of Towny 0.99.6.0 is it possible for towns to be put up for sale, using /t forsale [$] and bought by players using /t buytown [townname]. Towns are removed from sale using /t notforsale.

Mayors

Mayors run towns and with the help of their assistants, manage a town and its residents. Mayors have their permission nodes configurable via TownyPerms.yml.

Mayors can decide which ranks their residents fall into, in their town. This can be a Town Assistant or any other custom ranks created by the server admin in the townyperms.yml file. Mayors can see the available ranks using /town ranklist command. Players are ranked using /town rank {add|remove} {playername} {rankname}. A player can have more than one rank assigned, allowing admins to create diverse town-roles such as bankers, builders, inviters for the mayor to choose for their trusted residents.

Mayors also determine what sort of tax and tax rates the town will charge the residents.

It is not possible to run two towns unless you are also an admin. An admin can do the following to manage two or more towns:

Example: Admin Bob / How to create NPC Towns.

Admin Bob wants to have a server-town, and his own town. Bob would start by creating his Server Town and setting up taxes, plotprices, permissions. This sort of town should not give residents, allies or outsiders permissions in the Server Town.

Bob can give his town unlimited claims using /ta town {townname} toggle unlimitedclaims command.

When Bob is finished making his town the way he wants he uses /townyadmin set mayor {townname} npc to place a fake 'npc' resident as mayor of the Server Town. This is usually enough to protect the Spawn areas of most servers.

Then Bob leaves Server Town using /t leave and creates his own new town using /t new {townname}. Using the /townyadmin set mayor {townname} npc, /t leave, and /ta town {townname} add {playername} commands Bob can flip back and forth between towns.

Bob doesn't have to leave his town to add players to the Server Town though! He can use /townyadmin town {townname} add {playername} to add players to the Server Town or set default_town_name: 'Server_Town' in the config.yml. Many town settings can be configured using the /ta town {townname} commands.

Bob can also add the NPC town into a nation using /ta nation {nation} add {town}.

As an admin, Bob can also make NPC towns without having to leave his own town using the /ta town new {townname} npc command.

As of Towny 0.95.1.0 mayors have the ability to set titles (prefixes) and surnames (postfixes) to the residents of their town. This is done with:

  • /town set title {name} titlegoeshere
  • /town set surname {name} surnamegoeshere

Outlaws

As of Towny 0.92.0.0, towns (typically mayors by default, but possibly other town ranks,) can set a list of Outlaws. Outlaws are set using /town outlaw [add/remove] [name] and the command requires the towny.command.town.outlaw permission node. Outlaws can be any player and do not have to be in a town or nation.

If the newly-minted outlaw is a member of your town they will be kicked. Towns that have themselves set to Open-status (anyone can join using the /town join command,) can use the outlaw list to prevent these players from joining their town freely. Players cannot spawn to public towns which consider them outlaws.

Players that enter into a town where they are considered to be an outlaw will see a warning-title-message informing them. If a player is online and they are made into an Outlaw they will see a message in chat.

Outlaws can be jailed if they die in the town where they are considered to be an outlaw. This requires the jail.is_jailing_attacking_outlaws option in the Towny config.yml to be set to true. It also requires the person who's done the killing to have the towny.outlaw.jailer permission node. It also requires the town to own at least one jail plot. By default only Mayors, Assistants and Sheriff ranks have the towny.outlaw.jailer permission node.

A town member can view their town's outlaw list using /town outlawlist. Anyone can view any town's outlawlist using /town outlawlist {townname}.

A player can use /res outlawlist {playername} to display the list of towns in which the given playername is outlawed in. Leave out the optional player name to see the towns in which you are an outlaw.

As of Towny 0.96.4.0 you can optionally have outlaws teleport away from the towns they're not allowed in. When allow_outlaws_to_enter_town is set to false in the Towny config.yml outlaws will be teleported away. The outlaw_teleport_warmup setting will determine how quickly this will happen, when set to 0 it will be instant or it can be any number of seconds.

Nations

Click here for Major Graft's Towns & Nations Video A nation is a collection of towns (or just one town) with one town as the capital. The mayor of that capital is the nation leader. A nation can join the war event, as well as ally other nations. A nation also has it's own bank. It can also tax the towns that belong to it.

Nations can also have a spawn reached using /nation spawn which if the nation is considered 'Public' can be reached by nearly any non-enemy players. The nation spawn can be restricted to the capital in the config.yml at global_nation_settings.capital_spawn otherwise the spawn point can be anywhere in the nation.

Two nations can decide to join in an alliance, which allows them to be protected from friendly fire, help on each others plots (if the plot's perm line allows allies,) and to help each other in war. As of 0.91.0.0, you may restrict nation alliances to be 2-way only. So that Nation A cannot consider Nation B an ally unless the Nation B also considers Nation A an ally. You may turn this setting on in the config: war.disallow_one_way_alliance, which defaults to false.

Also, as of 0.91.0.0, you may restrict who can create, join and maintain a nation by requiring a minimum number of residents. See the Global Town Settings section of the config.yml.

As of 0.93.0.0, nations can grant a NationZone which surrounds the towns which are members. This is enabled at global_nation_settings.nationzone.enable in the config.yml. NationZones are just like normal wilderness except the only players which can modify the area are members of the nation. This can be useful to prevent greifing near to towns who have a nation. NationZones can be increased in size by increasing the population of the nation using the NationLevels in the config.yml, you can optionally make the capital town have a larger NationZone. NationZones can be disabled during war time in the config.yml at global_nation_settings.nationzone.war_disables. As of 0.97.3.0 NationZones can be toggled off by a mayor using /t toggle nationzone, and admins can set a specific size of NationZone for a Town using /ta town set nationzoneoverride #.

As of 0.96.2.0 you can configure a maximum number of residents per-town if they do not have a nation, at global_town_settings.maximum_number_residents_without_nation. When set above 0 towns will have to form nations to add more residents.

As of 0.100.1.0, you may set a maximum distance between the nation capital and towns which are allowed to join the nation. See the proximity section within the Global Nation Settings section of the config.yml. There are options that determine whether each town has to be close to the capital, and options that allow for the towns to be within a proximity of other towns in the nation (allowing nations to go wider,) as well as an optional hard-cap on how far a town can be from the Nation capital when they are within range of another town in the nation.

As of 0.100.1.0, nations can sanction towns. Doing this allows nations to prevent towns from using /n join to join the nation. It also prevents players using /n spawn [nationname] when the nation is considered public. Sanctioning towns is done via the /nation sanctiontown command.

Nations can grant many perks to their towns which can increase as the nation population increases, these include:

  • Bonus townblocks to be claimed.
  • Cheaper town upkeep costs.
  • Larger surrounding NationZones.
  • An increased outpost limit.

Nation Leaders

Nation Leaders lead Nations and are the mayor of the capital city. Leaders have their permission nodes configurable via TownyPerms.yml. Leaders can decide which ranks their residents fall into, in their nation. This can be a Nation Assistant or any other custom ranks created by the server admin in the townyperms.yml file. Leaders can see the available ranks using /nation ranklist command. Players are ranked using /nation rank {add|remove} {playername} {rankname}. A player can have more than one rank assigned, allowing admins to create diverse nation-roles such as bankers, inviters for the leader to choose for their trusted residents.

Leaders have the ability to set titles (prefixes) and surnames (postfixes) to the residents of the towns they have in their nation. This is done with:

  • /nation set title {name} titlegoeshere
  • /nation set surname {name} surnamegoeshere

Typing the commands with nothing after the player's name resets the title or surname to blank.

Configuring Mayor and Nation Leader Titles, Town and Nation Names

Towny gives you the ability to customize the naming scheme applied to Mayors, Nation Leaders, Towns, Capital Cities and Nations. This is done with two sections in the config.yml

Configuring town_level and nation_level

town_level:

  • The basic layout of the townLevel lines are as follows:
  - numResidents: 1
    namePrefix: ''
    namePostfix: ' (Settlement)'
    mayorPrefix: 'Hermit '
    mayorPostfix: ''
    townBlockBuyBonusLimit: 0
    townBlockLimit: 16
    upkeepModifier: 1.0
    townOutpostLimit: 0
    debtCapModifier: 1.0
    peacefulCostMultiplier: 1.0
    bankCapModifier: 1.0
    resourceProductionModifier: 1.0
    townBlockTypeLimits:
    - shop: 2
    - arena: 2

  - numResidents: 2
    namePrefix: ''
    namePostfix: ' (Hamlet)'
    mayorPrefix: 'Chief '
    mayorPostfix: ''
    townBlockBuyBonusLimit: 0
    townBlockLimit: 32
    upkeepModifier: 1.0
    townOutpostLimit: 1
    debtCapModifier: 1.0
    peacefulCostMultiplier: 1.0
    bankCapModifier: 1.0
    resourceProductionModifier: 1.0
    townBlockTypeLimits:
    - shop: 5
    - arena: 4

These are read as follows:

variable description
numresidents: 1 This is how many residents a town needs to reach the town_level.
namePrefix: '' This is added to the front of the town name.
namePostfix: ' (Settlement)' This is added to the end of the town name.
mayorPrefix: 'Hermit ' This is added to the front of the mayor's name.
mayorPostfix: '' This is added to the end of the mayor's name.
townBlockBuyBonusLimit: 0 This is the maximum number of plots which the town can buy using /town buy bonus.
Requires town.max_purchased_blocks_uses_town_levels set to true in the config.yml.
townBlockLimit: 16 This overrides the town_block_ratio config setting and decides how many townblocks a town gets.
Requires town_block_ratio: '0' set in the config.yml.
upkeepModifier: 1.0 Use a higher multiplier to increase the upkeep as towns get more residents.
Does not affect servers with town_plotbased_upkeep:true in which case it is based off of plot-count rather than resident-count, unless you've also got town_plotbased_upkeep_affected_by_town_level_modifier:true )
townOutpostLimit: 1 This is how many outposts a Town can claim.
Requires limit_outposts_using_town_and_nation_levels set to true in the config.yml.
debtCapModifier: 1.0 When debt_cap_uses_town_levels is set to true in the config.yml, the debt_cap override price will be multiplied by the debtCapModifier in the town_level. (Ex: debtCapModifier of 3.0 and debt_cap.override of 1000.0 would set a debtcap of 3.0 x 1000 = 3000.)
peacefulCostMultiplier: 1.0 Affects the cost a town will pay to remain neutral, based on the town population, multiplying population times the economy.price_town_neutrality in the config.yml.
resourceProductionModifier: 1.0 Alters the resources gained daily for a town from the TownyResources plugin.
bankCapModifier: 1.0 Affects the maximum amount a town is allowed to store in their town bank, based on the town population, multiplying population times the economy.banks.town_bank_cap in the config.yml.
townBlockTypeLimits townBlockTypeLimits is a list which may or may not be present. If a server wants to limit the amount of each Plot Type a town can have, this is where it is done. A list can be empty [] or it can have as many or as few of the plot types present.
  • The two levels above are for towns of 1 and 2 residents. When a town is created the mayor's new town has (Settlement) added to the end of his townname and he is given the prefix of Hermit. When the mayor gets a second resident his town becomes Townname (Hamlet) and he receives the prefix of Chief.

nation_level:

  • The basic layout of the nationLevel lines are as follows:
        -   numResidents: 10
            capitalPrefix: ''
            capitalPostfix: ''
            namePrefix: 'Federation of '
            namePostfix: ' (Nation)'
            kingPrefix: 'Count '
            kingPostfix: ''
            townBlockLimitBonus: 10
            upkeepModifier: 1.0
            nationTownUpkeepModifier: 1.0
            nationZonesSize: 1
            nationBonusOutpostLimit: 2
            peacefulCostMultiplier: 1.0
            bankCapModifier: 1.0

        -   numResidents: 20
            capitalPrefix: ''
            capitalPostfix: ''
            namePrefix: 'Dominion of '
            namePostfix: ' (Nation)'
            kingPrefix: 'Duke '
            kingPostfix: ''
            townBlockLimitBonus: 20
            upkeepModifier: 1.0
            nationTownUpkeepModifier: 1.0
            nationZonesSize: 2
            nationBonusOutpostLimit: 3
            peacefulCostMultiplier: 1.0
            bankCapModifier: 1.0

These are read as follows:

variable description
numResidents: 10 This is how many residents a nation must have to reach the nation level.
Note: This can be determined by the number of Towns instead of Residents if the global_nation_settings.nation_level_is_determined_by_town_count_instead_of_resident_count is set to true in the config.yml.
capitalPrefix: '' This is added to the front of the capital city of the nation.
capitolPostfix: '' This is added to the end of the capital city of the nation.
namePrefix: 'Federation of ' This is added to the front of the nation name.
namePostfix: ' (Nation)' This is added to the end of the nation name.
kingPrefix: 'Count ' This is added to the front of the nation-leader.
kingPostfix: '' This is added to the end of the nation-leader's name.
townBlockLimitBonus: 10 This is the number of bonus townblocks given to a town when they join a nation.
upkeepModifier: 1.0 Use a higher multiplier to increase the upkeep as nations get more residents (unless you use town_plotbased_upkeep:true in which case it is based off of plot-count rather than resident-count.)
nationTownUpkeepModifier: 1.0 Joining a nation will lower/raise how much town upkeep your town pays. This multiplier is calculated after all other multipliers have their effect on the town upkeep cost. When set at 1.0, there is no change to upkeep.
nationZonesSize: 2 How many plots wide the NationZone is surrounding a town.
nationBonusOutpostLimit: 2 How many outposts more that the town can claim on top of it's usual limit.
peacefulCostMultiplier: 1.0 Affects the cost a nation will pay to remain neutral, based on the nation population, multiplying population times the economy.price_nation_neutrality in the config.yml.
bankCapModifier: 1.0 Affects the maximum amount a town is allowed to store in their town bank, based on the town population, multiplying population times the economy.banks.town_bank_cap in the config.yml.

How Towns Grow

Starting a Town

Mayors start towns using the command /town new {townname}. This will often require an amount of money set in the config at price_new_town.

The townblock they are standing in will be the home block for the town, the exact spot/position will be the spawn point for the town. A mayor can move the spawn point within the homeblock using /t set spawn. The homeblock can be moved to another claimed townblock using /t set homeblock.

More townblocks can be claimed using /town claim. These townblocks need to be directly adjacent to already claimed townblocks, unless it is an outpost.

As of Towny 0.100.2.0 it is possible to grant new towns a one-time bonus number of TownBlocks. This is set in the config.yml at the claiming.new_town_bonus_claims setting.

Joining Towns

There are two ways to join towns, the first is by being invited by a Mayor or a Town assistant. The second is by joining an open town.

Mayors and assistants can add players to their town with the command /town add {playername}. The player will receive a prompt to either /accept or /deny the invitation.

Mayors can set their towns to open using /town toggle open. A player who isn't in a town already can use the command /town join {townname} to join open towns. Open towns can be viewed using the /town list by open.

When residents join towns they increase the number of townblocks accessible to the mayor for claiming.

Plot System of Land Ownership

Town Blocks

Towny provides a server admin a hands-off approach to block-protection. Block protection is broken down into plots of land, called townblocks, which by default are 16x16xN (where N is the full height of the world.) Think of them as cells on a uniform grid, all aligned and with no space in between each other, every one the same size. Townblocks are claimed by town mayors who can then sell/give individual plots to their town's residents.

As of Towny 0.95.1.0 it is possible to store MetaData on a townblock, see here for details.

Town Block Size

You change the townblock size in config.yml at town_block_size: 16. Changing this value is suggested only when you first install Towny. Doing so after entering data will shift things unwantedly. Using smaller value will allow higher precision, at the cost of more work setting up. Also, extremely small values will render the caching system used by Towny useless (it is not recommended to go below 4.) Each cell is (town_block_size x town_block_size x N) in size, with N being the full height of the world.

Claiming Townblocks

Town Claiming

Towns' residents can claim townblocks for the town as long as they have the right permission nodes. By default this is restricted to Mayors and people with the Assistant rank. The player uses /town claim or /town claim # or /town claim rect|circle #|auto or /town claim auto to claim townblocks for their town. In order to claim more than one plot at a time you must ensure you have given your mayor the towny.command.town.claim.town.multiple permission node.

command result
/town claim Claims one plot, where the player is standing.
/town claim # Claims a square with a radius equal to the given #, sometimes down-sizing the radius to make a perfect square, surrounding the command user.
/town claim rect # Claims a square with a radius equal to the given #, sometimes down-sizing the radius to make a perfect square, surrounding the command user.
/town claim rect auto Claims all possible townblocks in a square shape, centered around the command user.
/town claim circle # Claims a circle with a radius equal to the given #, sometimes down-sizing the radius to make a perfect circle, surrounding the command user.
/town claim circle auto Claims all possible townblocks in a circle shape, centered around the command user.
/town claim auto Claims all possible townblocks in a square shape centered around the command user.
/town claim fill Flood fills an area that has been surrounded by a border of claims. This will not work until a border/ring of claims has been made.

Using the /town command will list how many townblocks are available to be claimed.

As of 0.95.0.0 you may set a refund amount for unclaiming townblocks at economy.new_expand.price_claim_townblock_refund, it is not recommended that this be set at or higher than the cost to claim a townblock. As of 0.98.0.0 you may set the refund amount to a negative number, allowing you to charge players to unclaim their land.

As of 0.95.0.0 you may make the cost of claiming townblocks increase at economy.new_expand.price_claim_townblock_increase. When set to 1 this is deactivated. 1.3 means +30% to every bonus claim block cost. Cost increase can be seen in /towny prices output.

As of 0.96.3.0 you can set the maximum price that the economy.new_expand.price_claim_townblock_increase can reach. This is set at economy.new_expand.max_price_claim_townblock in the config.yml.

As of 0.99.0.0 you can force Towns to claim their land in different shapes. The claiming.min_adjacent_blocks found in the config.yml sets a rule on how many adjacent townblocks must be next to a plot in order to be claimed by a town. By default this is set to -1 and is inactive but when set to 2 or 3 it can be used to prevent claiming in straight lines.

As of 0.100.1.0 you can now blocks town claiming in ocean biomes and separately unwanted biomes. Both options are found the biome rules section within the claiming section of the config.yml. TownBlocks which would have too high a percentage of the ocean or unwanted biomes will not be allowed to be claimed. Using these features you can make oceans, rivers, mountains unclaimable, allowing for a unique look.

Personal (Player) Claiming

When a townblock has been claimed by a town using /town claim the mayor can put the townblock/plot up for sale using /plot fs {optional cost}. After a plot is put up for sale, a town resident can claim the land personally using /plot claim. Likewise, plots are unclaimed by residents by using /plot unclaim.

Cede-ing Land

As of Towny 0.100.2.0 players can now voluntarily give up land to other towns. This is done using the /town cede plot [townname] command. In order to a town to be able to cede land, the town inheriting the plot must be able to claim the land if it were unclaimed and available to use /t claim. This means that the interiting town must have the available townblock to claim, must have an adjacent claim and must also obey all proximity rules. When the /t cede plot [townname] command is used the player using the command must confirm their command, and the receiving mayor must also be online to confirm recieving the plot.

Setting How Many Town Blocks A Town Receives

You can change how many town blocks a town gets to claim. This is done in two places. Towny checks first in the config.yml at town_block_ratio: 8 and by default gives a town 8 townblocks per resident. You can override this by setting town_block_ratio: 0 and using the town_level section of the config.yml More information on the town_level line and how to configure it is here. The config setting town.town_block_limit determines the absolute maximum number of TownBlocks a Town can accrue, when the setting is larger than 0.

As of Towny 0.98.0.0 it is possible for a town to receive an unlimited amount of townblocks. This is done via the config, by setting the town_block_ratio to -1 (affecting all towns,) or via the /ta town TOWNNAME toggle unlimitedclaims command (affecting just one town.)

Buying Townblocks

Normally Towny limits a town's townblocks to a number based on resident count or town_level. Towny allows towns to purchase additional townblocks that the town can then claim, using /town buy bonus {amount}. There are two methods you can limit how many townblocks can be purchased by a town:

  1. If town.max_purchased_blocks_uses_town_levels is set to false: the max is set in the config.yml at max_purchased_blocks: '0'.
  2. If town.max_purchased_blocks_uses_town_levels is set to true: the max is dictated via the town_level's townBlockBuyBonusLimit setting, allowing towns with more residents to purchase more townblocks.

The price of a bought townblock is also set in the config.yml at price_purchased_bonus_townblock: '25.0'. The price can be configured to increase with each purchase using the price_purchased_bonus_townblock_increase: '1.0' config setting. Using this feature, mayors can grow their town without needing new residents. Increasing costs can be seen in /town buy bonus output.

As of Towny 0.96.3.0 you can set a maximum price that the price_purchased_bonus_townblock_increase will be able to go to. This is set at economy.new_expand.price_purchased_bonus_townblock_max_price in the config.yml.

Admins are able to give/take these purchased townblocks from towns using the /ta town TOWNNAME giveboughtblocks [#|unset] command. Use a negative number to remove townblocks, or unset to remove all purchased townblocks.

Overclaiming Townblocks

As of Towny 0.99.1.0, a feature called Overclaiming has been added to Towny. It is disabled by default and has to be enabled at town.overclaiming.being_overclaimed_allows_other_towns_to_steal_land in the config.yml.

When the feature is enabled towns which have become "overclaimed". Towns are considered "overclaimed" when their townblock limit is less than what they have claimed, ie: 120/100 TownBlocks.

Land is stolen one plot at a time using the the /t takeoverclaim command. It has some requirements:

  • This command must be used at the edge of a town, which is adjacent to your town.
  • Your own town cannot be overclaimed.
  • You must be able to pay the special cost set in the config at economy.takeoverclaim.price
  • Towns can only have land stolen from them until they are no longer overclaimed!
  • (Optionally) the town that is overclaiming land from another might have to be of a certain age, preventing new towns from being made to overclaim land.
  • (Optionally) there might be a cooldown on using the `/t takeoverclaim' command.

TownBlocks that can be stolen will have a [TakeoverClaim Available] added to their ChunkNotification.

Mayors of overclaimed towns, and potentially-soon-overclaimed towns will see various messages warning them:

  • on login while being overclaimed,
  • when they approach their claim limit while claiming land,
  • and when they lose a resident that would put them at risk of being overclaimed.

Overclaiming does not allow a town to be split into two separate parts, requiring the Town that is stealing land to work from the outside inwards.

Important:

  • It is highly recommended to only use this on servers where outposts are disabled, and requiring a number of adjacent claims over 1 is enabled.
  • There is an option to prevent stealing land too close to a Town's HomeBlock in the config at town.overclaiming.overclaiming_prevented_by_homeblock_radius!

As of 0.100.1.0 there is an option that can limit Overclaiming of nations' land to only be done by enemies. This is located at claiming.overclaiming.nations_required_to_be_enemies in the config.yml.

Plot Groups

Plots can be grouped together into plot groups. This allows plots to be sold/bought and manipulated as if it were one Plot. To create a group a player must have the proper permissions to operate on it. The player then stands in the plot and executes: /plot group add {group_name}, Towny will add the plot you're standing in, into a group if it exists, or create a new one if a group with that name doesn't exist. Simply repeat the command /plot group add {same_group_as_above} while standing in other plots to add those plots to the group.

Most of the other commands used to manipulate plots are the same with one exception, instead of starting with the prefix /plot, plot group operations start with the /plot group prefix. For example to set a property for sale you do /plot fs 10000, but for a plot group named highlands you would do /plot group fs 10000. Perms, types and others follow this convention. See /plot group ? for full command list.

As of Towny 0.99.6.0 it is now possible to add plots to a plotgroup by walking into them with a new resident mode: plotgroup. When a player has a plotgroupname set in memory any plot they want into will automatically join the plot group. The plotgroupname is set into memory when a player uses the /plot group add NAME command. In this way, a player can use /plot group add NAME to begin a plot group, and then use /res toggle plotgroup to turn on the resident mode, then begin adding plots to the plot group by walking around, using /res toggle plotgroup when they are finished.

Districts

Plots can be grouped together into districts. Districts are similar to Plot Groups but come with less restrictions: Districts' townblocks are not required to have the same plot permissions, plot type, owner or plot name.

Districts are handy for naming sections of a town, or creating neighbourhoods.

Districts show their name in the chunk notifications, map hud, and in the /towny map hover text.

Townblocks in a district are required to be adjacent to each other.

Plot Types

Click here for Major Graft's Video about Plot Types Players can use `/town plots {townname}` to view the counts of various plot types in a town. Towny post-0.75 has added plot types besides the default. This is to give mayors more control over their towns.

A plot's cost to create (using the /plot set {plottype} command,) and the plot tax paid by the player to keep ownership of the plot are set in the townblocktypes.types section of the config.

As of Towny 0.98.4.0 you can limit how many of each plot type a town can have using the town_level's townBlockTypeLimits list.

As of Towny 0.98.0.0 you can create any number of TownBlock Types! Your config contains a townblocktypes section. In it you will find the below plot types, but you can add your own as well. It is not recommended that you remove any types added by default though.

Custom Plot Types

A custom plot type consists of 7 elements:

key explanation
name the name used for this townblock, in-game and in the database.
cost Cost a player pays to set a townblock to the type.
tax The amount a player has to pay city each day to continue owning the plot. If tax is set to 0, the towns' plot tax will be used instead.
mapKey The character that shows on the /towny map commands.
itemUseIds If empty, will use values defined in the protection.item_use_ids. If not empty this defines what items are considered item_use actions when stood in the plot type.
switchIds If empty, will use values defined in the protection.switch_ids. If not empty this defines what blocks are considered switch actions when stood in the plot type.
allowedBlocks A list which will make it so players with build or destroy permissions are only able to affect those blocks, see the farm type for an example. When empty, the normal build/destroy blocks apply.

As of Towny 0.99.6.0 you can apply colours to TownBlockTypes: by default new configs will have a colour: for each TownBlockType. Older config files can add this option to their existing TownBlockTypes if they want. The colour will be used in the /towny map outputs.

The plot types that Towny provides are as follows:

Default Plots

These plots do not need any specific command to be designated. They are put up for sale with /plot forsale {$$}. A plot which is not of default type can be reset to a default plot with /plot set reset.

Shop Plots

Shop plots are designated with /plot set shop. A mayor can use /town set shopprice {$$} to set how much shop plots are sold at by default. This can be overridden when a mayor puts the actual plot up for sale with /plot forsale {$$}. A mayor can also charge an additional shoptax with /town set shoptax {$$}. This tax is charged in addition to the normal plottax.

Some shop plugins are able to be restricted to Shop Plots only. This can be nice for enforcing shopping districts.

A shop plugin that wants to use Towny's API to limit their shops to Shop Plots can do so easily using the information found on the TownyAPI wiki page.

Shop Plugins that already support this include (but are not limited to,)

Arena Plots

Arena plots are designated with /plot set arena. PVP is on all the time in arena plots as well as friendly-fire damage. Town health regen is also disabled in arena plots.

Embassy Plots

Embassy plots are designated with /plot set embassy. A mayor can use /town set embassyprice {$$} to set how much embassy plots are sold at by default. This can be overriden when a mayor puts the actual plot up for sale with /plot forsale {$$}. A mayor can also charge an additional embassytax with /town set embassytax {$$}. This tax is charged in addition to the normal plottax. An embassy plot can be bought by any player, whether they are in a town or not, as long as they have the towny.command.plot.claim permission node. The townblock remains owned by the host-town and a mayor from the host-town can take the plot from the owner at any time. Embassy plots can also be changed into shop plots, allowing for larger shop towns, where many different towns' players can set up shops. When a player leaves a town they do not lose ownership of their plots if those plots are set to be Embassy plots.

Wilds Plots

Wilds plots are designated with /plot set wilds. A wilds plot allows residents to destroy the blocks found on the wild ignore ID list. This includes ores, trees, flowers, mushrooms and other harvestable blocks by default. It does not include stone, dirt, grass and other terrain blocks. It is useful for creating tree farms, and protecting the terrain around a town, while still allowing residents to cut trees and explore caves.

A player can use /towny wildsblocks to see a server's allowed wilds plots blocks.

Setting up wilds plots can be slightly complex, here are instructions.

  1. Navigate to your towny\data\worlds\WORLDNAME.txt file

  2. Set:

    • unclaimedZoneBuild=false
    • unclaimedZoneDestroy=false

  3. Configure the unclaimedZoneIgnoreIds line to include the blocks you would like players to break/build.

  4. Go to the Wilds plots you can set using /plot set wilds

By default residents will have build/destroy enabled for them, you can also set allies or outsiders perms if you want non-town-members to use the Wilds plots.

Inn Plots

Inn plots are designated with /plot set inn. Inns are most useful when the deny_bed_use setting is true in the config.yml. This setting makes it so that players cannot use beds in plots they do not personally own, except when that plot is an Inn plot.

Inn plot allows anyone to use a bed to set their /res spawn and spawn on death locations. However, Inn plots cannot be used by enemies of your nation.

Jail Plots

Jail plots are designated with /plot set jail.

Players can become jailed if:

  • The player's mayor/sheriffs send them to jail using one of the following commands:

    • When Bail is Disabled:
    • /town jail [name] - Jails the given player for 1 hour, must be a resident of your own town.
    • /town jail [name] {hours} - Jails the given player for the given hours.
    • /town jail [name] {hours} {jail} - Jails the given player for the given hours, in the given jail plot (which is a number.)
    • /town jail [name] {hours} {jail} {cell} - Jails the given player for the given hours, in the given jail plot and jail cell (which are both numbers.)
    • When Bail is Enabled:
    • /town jail [name] - Jails the given player for 1 hour, must be a resident of your own town, with the default bail amount.
    • /town jail [name] {hours} - Jails the given player for the given hours, with the default bail amount.
    • /town jail [name] {hours} {bail} - Jails the given player for the given hours, with the given bail amount.
    • /town jail [name] {hours} {bail} {jail} - Jails the given player for the given hours, with the given bail amount, in the given jail plot (which is a number.)
    • /town jail [name] {hours} {bail} {jail} {cell} - Jails the given player for the given hours, with the given bail amount, in the given jail plot and jail cell (which are both numbers.)

  • An attacker who attacks a town which considers him an Enemy (Nation-relationship) dies in that Town. He is sent to the defending town's primaryjail.

  • An attacker who attacks a town which considers him an Outlaw dies in that Town by a player with the towny.outlaw.jailer permission node. He is sent to the defending town's primaryjail. In the config jail.is_jailing_attacking_outlaws must be true.

Jailed players become unjailed if:

  • they leave their town and become a nomad,
  • the mayor/sheriff unjails them,
  • the player pays a bail amount to the town which jailed them, (using: /resident jail paybail)
  • they manage to escape the jail plot and the town and get into Wilderness.

In addition:

  • Jailed players cannot teleport.
  • Jailed players cannot use Ender Pearls or Chorus Fruit unless enabled in the config.
  • Jailed players who die are sent back to their prescribed jail plot.
  • Jailed players do not give monetary payouts when they are killed.
  • Jailed players show their jailed status in the /res [playername] screen, along with the town they are jailed in.
  • It is suggested you make a new town rank in the townyperms.yml called Sheriff, and give that rank the towny.command.town.toggle.jail node. Newly generated townyperms.yml files will contain this rank by default.
  • There is a list in the config at jail.blacklisted_commands where you can set a list of commands which jailed players cannot use.

Also:

  • Optionally in the config: newly-jailed players who log out before they can be teleported to their cell will be killed.
    • The player is warned to prevent surprises.
    • Works similar to many combat-logging plugins.
  • Optional new-player jail immunity
    • Set in the config, how long a new player to the server is protected from being jailed.

Jail plots can have multiple jail cells in them. Jail cells are made using /plot jailcell add and removed using /plot jailcell remove. Jail cells' spawn locations are marked ingame using a ring of particles.

A town can see a list of their jails using /town jail list. A town sets their primaryjail using /town set primaryjail while standing in a jail plot. Their first jail will automatically become the primaryjail.

Players which are jailed will receive a nice book explaining to them how they can get out of jail, with information pulled from the the server's config file.

The Bail System available to jails is something which must be enabled in the config.yml at jail.bail.is_allow_bail. While enabled players can pay money in order to get released from jail. There are default bail costs for when outlaws and enemies are jailed via being killed, as well as default amounts for mayors and kings which are killed. When a town resident is jailed via the jail command, the bail can be specified in the command used, with player being limited to a maximum value which is configured at jail.bail.bailmax_amount in the config.yml.

Farm Plots

Click here for Major Graft's Video about Plot Types

Farm plots are designated with /plot set farm. A Farm plot players to only build/destroy blocks designated in the Towny config.yml at global_town_settings.farm_plot_allow_blocks. By default this list includes: BAMBOO,BAMBOO_SAPLING,JUNGLE_LOG,JUNGLE_SAPLING,JUNGLE_LEAVES,OAK_LOG,OAK_SAPLING,OAK_LEAVES,BIRCH_LOG,BIRCH_SAPLING,BIRCH_LEAVES,ACACIA_LOG,ACACIA_SAPLING,ACACIA_LEAVES,DARK_OAK_LOG,DARK_OAK_SAPLING,DARK_OAK_LEAVES,SPRUCE_LOG,SPRUCE_SAPLING,SPRUCE_LEAVES,BEETROOTS,COCOA,CHORUS_PLANT,CHORUS_FLOWER,SWEET_BERRY_BUSH,KELP,SEAGRASS,TALL_SEAGRASS,GRASS,TALL_GRASS,FERN,LARGE_FERN,CARROTS,WHEAT,POTATOES,PUMPKIN,PUMPKIN_STEM,ATTACHED_PUMPKIN_STEM,NETHER_WART,COCOA,VINE,MELON,MELON_STEM,ATTACHED_MELON_STEM,SUGAR_CANE,CACTUS,ALLIUM,AZURE_BLUET,BLUE_ORCHID,CORNFLOWER,DANDELION,LILAC,LILY_OF_THE_VALLEY,ORANGE_TULIP,OXEYE_DAISY,PEONY,PINK_TULIP,POPPY,RED_TULIP,ROSE_BUSH,SUNFLOWER,WHITE_TULIP,WITHER_ROSE,CRIMSON_FUNGUS,CRIMSON_STEM,CRIMSON_HYPHAE,CRIMSON_ROOTS,MUSHROOM_STEM,NETHER_WART_BLOCK,BROWN_MUSHROOM,BROWN_MUSHROOM_BLOCK,RED_MUSHROOM,RED_MUSHROOM_BLOCK,SHROOMLIGHT,WARPED_FUNGUS,WARPED_HYPHAE,WARPED_ROOTS,WARPED_STEM,WARPED_WART_BLOCK,WEEPING_VINES_PLANT,WEEPING_VINES,NETHER_SPROUTS

Players can use /towny allowedblocks to see a list of a server's farmblocks.

Who can build/destroy these blocks is still determined by the plot's perm line seen in the /plot perm screen. This means that if B=rnao, anyone can plant/place the allowed blocks in the plot. If the B=r--- then only town residents can plant/place the allowed blocks.

If admins want, they can add FARMLAND to the allowed blocks list, which will allow anyone allowed via the perm line to also make farmland with a hoe. By default FARMLAND is not included and only admins/mayors/assistants will be able to create farmland with a hoe. Towny already protects farmland from being stomped into grass, so farmland will only return to dirt if it is not irrigated.

Farm plots also allow player to kill animals in the plot. In order to kill the configured animals list the player must be able to break wheat blocks on the plot. The list of animals is set in the config at global_town_settings.farm_animals. By default this list includes PIG,COW,CHICKEN,SHEEP,MOOSHROOM.

Bank Plots

Bank plots are designated with /plot set bank. Bank plots can be used to limit town and nation bank depositing/withdrawing. By default this setting is off but can be turned on at bank.is_banking_limited_to_bank_plots in the config.yml Bank plots are more useful for other plugins which would want to limit their banking features to within Towny bank plots.

As of 0.100.1.0 there is an option that forces town deposit/withdraw to happen only in bank plots, preventing the use of the homeblock, when a town has at least one bank plot. This is enabled at bank.do_homeblocks_not_work_when_a_town_has_bank_plots in the config.yml.

Outposts

Normally townblocks are claimed around the home block, always connected to the town's other townblocks. To claim a townblock out in the wilderness or in another world, a mayor or assistant must claim an outpost. In order for players to claim outposts, the config must be set to allow_outposts: true and players require towny.town.claim.outpost in their permission node group. The outpost list can be viewed by using /town outpost list command. The spawn point inside of an outpost townblock can be moved using the /plot set outpost spawn or /t set outpost command.

The residents of the Town can teleport to outposts to using /town outpost x|name|name:x

  • with x being a number 1 - however many outposts the town has
  • where name is the plot name of the outpost (seen in /t outpost list and set using /plot set name {name}.)
  • where name:1asdasda - useful for when a plot name begins with a number.

An admin can configure how many outposts a player can claim, this is set in your permissions plugin's info/option/meta node section using the towny_maxoutposts: {number} info node. See here.

Alternatively, as of 0.93.0.0, you can use the config.yml's town_level and nation_level maxoutpost values to give larger towns more outposts to claim, and bonus outposts to towns in nations. This requires enabling the feature in the config.yml at global_town_settings.limit_outposts_using_town_and_nation_levels.

An admin can also set a number of residents required by a town before they can claim outposts, using the minimum_amount_of_residents_in_town_for_outpost setting. By default there is no resident requirement.

Outposts cannot be claimed too close to other home blocks, just like when a mayor starts a town they cannot be too close. The exact number is set in the config.yml at min_distance_from_town_homeblock: 5. In the default setting an outpost cannot be claimed within 5 townblocks of any other homeblock.

You can also configure how close an outpost can get to any other town's plots using town.min_distance_for_outpost_from_plot.

You can also set the cost of claiming an outpost in the config.yml at price_outpost: 500.0.

Buying and Selling Land

Click here for Major Graft's Plot Claiming Video Land is sold by Mayors to Residents that are a part of their town. `using_economy: true` must be set in [config.yml](https://github.com/TownyAdvanced/Towny/wiki/Default-Config.yml) in order for costs to be applied. Mayors have a command used in game to set the cost of all the plots that are set for sale hence-forth.

  • /town set plotprice {$}
    • This sets the cost of newly-set-for-sale plots, already set-for-sale plots keep their costs.
    • If it is not set, the plots will cost $0 by default.
To put a plot up for sale a mayor, while standing in the plot, type `/plot forsale {optional cost}`. The resident would then type `/plot claim` (while standing in the plot,) to buy it.

Mayors can specify a date range that the resident must be a member of the town for, in order to claim the land. This is done using two commands: /t plot set minjoindays {#} and /plot set maxjoindays {#}. When these commands are used, this means that residents cannot use /plot claim on the plot that is for sale, unless they have been a resident for a long or short enough amount of time. When set, the min join days number will mean that a resident would have to be a resident of the town for a minimum of X days. When set, the max join days number will mean that a resident would have to be a resident of the town for a maximum of X days. These values are showing on the /plot info screen, as well as in the denial message seen when /plot claim fails.

Embassy plots are not affected by the min and max join days, unless it is being claimed by a town resident. In order to remove the requirements, mayors can use the word clear in place of the {#}.

Preventing areas from being claimed

There are three ways to prevent people from claiming land.

  1. The first is to make an entire world unable to be claimed: while in the world use /tw toggle claimable. This will prevent anyone from making a town and claiming land (including outposts.)

  2. The second method is to make your own town at the location, no one can claim something that has already been claimed:

    If you already have a town use /ta set mayor TOWNNAME npc. Then use /t leave. Then start your town at the location you don't want to have claimed. If you need more townblocks, as an admin you can use /ta town TOWNNAME toggle unlimitedclaims to give your town more townblocks to claim with. When you're finished claiming simply use /ta set mayor TOWNNAME npc and then /t leave. Your newly-made NPC town will not have to pay any upkeep and will be a permanent town on your server. To rejoin your previous town use /ta town TOWNNAME add YOURNAME and then /ta set mayor YOURTOWN YOURNAME.

  3. The third method is to use WorldGuard-Towny. When this plugin is installed on your server, any WorldGuard region which has had the town-creation flag added to it will not allow for any Towny claim to be made.

Using the Maps

The map in towny displays the grid system of plots. The map can be viewed once using /towny map one time or you can set the map to show every time you move from one block to another:

  • Use /resident toggle map to turn it on or off.

A larger version of the map can be seen using /towny map big.

A hud version of the map can be seen using /towny map hud.

As of Towny 0.99.6.0 it is possible to define the dimensions of the /towny map output in the config.yml at the ascii_map_symbols.map_height and ascii_map_symbols.map_width entries.

Plot Regeneration & Unclaimed Plots

There are 4 options for affecting townblocks/plots.

Reverting unclaimed townblocks to their original state on unclaim

When a town plot is unclaimed (by a player using /t unclaim or through upkeep) it will slowly begin to revert to a pre-town state. Blocks will slowly change back to a snapshot taken of the plot when it was first claimed. A townblock must revert completely before the snapshot of the townblock is removed. If townblock is reclaimed mid-revert, a new snapshot is not taken and if the townblock is unclaimed again it will revert to the original snapshot.

  • Disabling this feature is done in the towny\data\worlds\worldname.txt @ usingPlotManagementRevert=false,
  • or by using /tw toggle revertunclaim while standing in the world you want to toggle it in.
  • Disabling this feature for new worlds is done in the config at new_world_settings.plot_management.revert_on_unclaim.enabled.

You can configure certain block types you don't want restored to prevent players exploiting regen for diamond ores.

  • Block types to not restore are configured in plotManagementIgnoreIds in the world's txt file towny\data\worlds\worldname.txt.
  • Defaults for new worlds are set in the config at new_world_settings.plot_management.revert_on_unclaim.block_ignore

Alternatively, you can use a whitelist to only restore blocks on the list:

  • The whitelist is set in the world's revertOnUnclaimWhitelistMaterials="" line.
  • When this is empty the whitelist does not function and the plotManagementIgnoreIds list is used instead.
  • Defaults for new worlds are set in the config at new_world_settings.plot_management.revert_on_unclaim.block_whitelist.
  • This list is useful for when you want only 'natural' blocks to regenerate like stone, grass, trees, etc., useful when you allow players to build/destroy in the wilderness.

As of Towny 0.99.6.0, Towny now contains support for CoreProtect, and blocks which have been reverted by Towny should appear to CoreProtect, if you should have reason to want to revert a revert that already took place.

Deleting pre-defined blocks on unclaim

When a town plot is unclaimed (by a player using /t unclaim or through upkeep) block materials matching a list will be deleted within that townblock. This can be useful for deleting all signs within a townblock, ensuring any chests locked with Lockette or Deadbolt signs are unlocked.

  • Disabling this feature is done in the towny\data\worlds\worldname.txt @ usingPlotManagementdelete=false
  • Disabling this feature for new worlds is done in the config at new_world_settings.plot_management.block_delete.enabled

You can configure the list of Material names to be removed on a per-world basis.

  • The materials listed in the towny\data\worlds\worldname.txt @ plotManagementDeleteIds= will be removed from the townblock.
  • Defaults for new worlds are set in the config at new_world_settings.plot_management.block_delete.unclaim_delete

Plot-Owners' and Mayors' /plot clear command

A feature available only to Town Mayors on public town land: /plot clear. This command is meant to be used after a plot was personally owned by a resident, who either moved to another plot or left town. By default this list includes only signs, useful for mayors to remove sign-protection on doors, chests, furnaces, dispensers and trapdoors given via Lockette or Deadbolt.

A player can use /towny plotclearblocks to see which blocks will be removed when /plot clear is used.

  • Disabling this feature is done in the in the towny\data\worlds\worldname.txt @ usingPlotManagementMayorDelete=false or via the /tw toggle plotcleardelete command, in the applicable world.
  • Disabling this feature for new worlds is done in the config at new_world_settings.plot_management.mayor_plotblock_delete.enabled

You configure the list of Material names to be removed when this command is used.

  • The list of blockIDs is listed in the towny\data\worlds\worldname.txt @ plotManagementMayorDelete=
  • Defaults for new worlds are set in the config.yml at new_world_settings.plot_management.mayor_plotblock_delete.mayor_plot_delete

As of Towny 0.79.1.0, players can use this command within plots they personally own.

Wilderness Regeneration

The wilderness explosion regeneration has two settings:

Entity Explosions

This feature regenerates explosions made by entities, such as TNT, Creepers, WitherSkulls, EnderDragons and others (it is a configurable list.) These settings are copied to the individual world files, so you must make changes per world.

  • Disabling this feature for entity explosions is done in the in the towny\data\worlds\worldname.txt @ usingPlotManagementWildRegen=true
  • or by using '/tw toggle revertentityexpl' while standing in the world you want to toggle it in.
  • Disabling this feature for new worlds is done in the config at new_world_settings.plot_management.wild_revert_on_mob_explosion.enabled
  • The list of entities whose explosions will revert is set in the towny\data\worlds\worldname.txt @ PlotManagementWildRegenEntities
  • The default list applied to new worlds is set in the config.yml @ new_world_settings.plot_management.wild_revert_on_mob_explosion.entities

Block Explosions

As of Towny 0.96.3.0 you can now specify a list of blocks whose explosions will be reverted (think: beds in the nether,) again per-world with the default for new worlds set in the config.

  • Disabling this feature for block explosions is done in the in the towny\data\worlds\worldname.txt @ usingPlotManagementWildRegenBlocks=true
  • or by using '/tw toggle revertblockexpl' while standing in the world you want to toggle it in.
  • Disabling this feature for new worlds is done in the config at new_world_settings.plot_management.wild_revert_on_mob_explosion.enabled
  • The list of blocks whose explosions will revert is set in the towny\data\worlds\worldname.txt @ PlotManagementWildRegenBlocks
  • The default list applied to new worlds is set in the config.yml @ new_world_settings.plot_management.wild_revert_on_block_explosion.blocks

Alternatively, you can use a whitelist to only restore blocks on the list:

  • The whitelist is set in the world's PlotManagementWildRegenBlockWhitelist="" line.
  • When this is empty the whitelist does not function and the PlotManagementWildRegenBlocks list is used instead.
  • Defaults for new worlds are set in the config at new_world_settings.plot_management.wild_revert_on_explosion_block_whitelist.

These two kinds of Wilderness Regeneration also come with an optional list of blocks that won't be overwritten. This is useful in a situation where someone dies in a creeper explosion, and you use a death chest plugin. Without adding CHEST to the list, your player death chests might be replaced by the ground that is reverted in the explosion's pit.

  • The list is set in the world's wildRegenBlocksToNotOverwrite="" line.
  • When this is empty every sort of block will be replaced.
  • Defaults for new worlds are set in the config at new_world_settings.plot_management.wild_revert_explosions_blocks_to_not_replace.

Explosion revert delay

You can configure how quickly the blocks will regenerate, specifically how much time in between each block being reverted.

  • The timer is changed in the towny\data\worlds\worldname.txt @ usingPlotManagementWildRegenDelay=5
  • The default for new worlds is set in the config.yml at new_world_settings.plot_management.wild_revert_on_mob_explosion.delay

How Towny Lets Players Protect Their Blocks

Towny's genius is the way it lets players protect themselves. An admin doesn't need to go around protecting land for players, and players can't run rampant claiming massive amounts of land without working for it and building their towns.

Available in Towny 0.77.0.0 and onward are per-plot permissions. When a plot is claimed by a mayor for their town using /town claim the plot will receive the perm line seen in the /town status screen. When a plot is claimed by a resident from a town using /plot claim the plot will receive the perm line see in the /res status screen. The owner of the plots can set different perms to different plots. To view a plots perm type /plot perm and to set a plots' perms use /plot set perm.

The first concept you need to digest are the 4 perm-types and 4 groups.

Towny Plot Perms

There are 4 permission-type values, which can be set for personal plots and for town plots as well (town permissions can be set by the mayor and affect plots who are not owned by any player.) The basic command for this is either /resident set perm or /town set perm followed by the proper flags for each permission.

Players can see the server's switch blocks by using the towny switches command.

Players can see the server's item_use items by using the towny itemuse command.

An admin player can test permissions, or otherwise act as a normal player by using /res toggle adminbypass. The same command is run to remove the adminbypass mode. While in adminbypass mode the player will not be able to act as an admin in plots (as well as other places in Towny.)

Perm-Types

The 4 permission-types available are Build, Destroy, Switch and Itemuse.

  • Build allows players to add blocks in your town/plot.

  • Destroy allows players to remove blocks in your town/plot, or in some cases alter the states of existing blocks (think changing redstone repeater settings.)

  • Switch covers the use of:

    • CHEST,
    • SHULKER_BOXES,
    • TRAPPED_CHEST,
    • FURNACE,
    • BLAST_FURNACE,
    • DISPENSER,
    • HOPPER,
    • DROPPER,
    • JUKEBOX,
    • STONECUTTER,
    • SMITHING_TABLE,
    • FLETCHING_TABLE,
    • SMOKER,
    • LOOM,
    • GRINDSTONE,
    • COMPOSTER,
    • CARTOGRAPHY_TABLE,
    • BELL,
    • BARREL,
    • BREWING_STAND,
    • LEVER,
    • PRESSURE_PLATES,
    • BUTTONS,
    • WOOD_DOORS,
    • FENCE_GATES,
    • TRAPDOORS,
    • MINECARTS,
    • LODESTONE,
    • RESPAWN_ANCHOR,
    • TARGET
    • .... or any other type of block which is clicked on.

  • Itemuse covers the use of:

    • MINECARTS,
    • BOATS,
    • ENDER_PEARL,
    • FIREBALL,
    • CHORUS_FRUIT,
    • LEAD
    • .... or any other type of item which is used in some manner.

  • ItemUse and Switch lists have the follow pre-configured catch-all groups you can add to them: BOATS,MINECARTS,WOOD_DOORS,PRESSURE_PLATES,FENCE_GATES,TRAPDOORS,SHULKER_BOXES,BUTTONS.

  • Note: Vehicles like MINECARTS and BOATS can be added to the switch_ids. If you want to treat other rideable mobs like switches add SADDLE to protect HORSES, DONKEYS, MULES, PIGS, STRIDERS (This is not recommended, unless you want players to not be able to re-mount their animals in towns they cannot switch in.)

Perm-Groups

Click here for Major Graft's Towns & Nations Video

Each permission-type has 4 perm-groups to which the pemissions can be set for.

The four perm-groups are:

  • Friend/Resident
  • Town/Nation
  • Ally
  • Outsider

These are displayed on your /resident perm line as FTAO and stand for Friend, Town, Ally, Outsider. For residents the Friend group consists of a player's friend list and Town consists of townmembers.

For towns, the perm line reads RNAO, with R representing Residents (players in that town) and Nation representing residents of towns in your nation.

Mayors need to use /t set perm resident blah on/off instead of /t set perm friend blah on/off.

The other groups are:

  • Ally
    • On personally-owned plots allies consist of players in your nation and players in your nation's allies.
    • On town-owed plots it is players in your nation's allies.
  • Outsiders
    • Players who are not part of your town or nation or nation's allies.

All commands are found on the Wiki's Commands page.

Setting perms in-game with commands

Click here for Major Graft's Plot Permission Video Setting perms for your town's public land or your personal plots is easy! There are two distinct levels of protection provided by towns. First are the town blocks, protected because they are part of a town and not owned by anyone. When you enter one of these plots from the wilderness or an owned plot the notification will show "~ Unowned". Mayors are able to set the permission for unowned plots using the the `/town set perm` command. A full list of commands is on the [commands](https://github.com/TownyAdvanced/Towny/wiki/Towny-Commands) page, here are some examples:

  • /town set perm {on/off} - This turns on or off all permissions for all perm-types and all perm-groups.
  • /town set perm ally {on/off} - This turns on or off all perm-types and for the town's allies (Nations to which their nation is allied with.)
  • /town set perm resident build {on/off} - This turns on or off all permissions for building done by residents of the town.

Second are the town blocks owned personally by a resident of a town. A resident is able to set the permission for unowned plots using the the /resident set perm command. A full list of commands is on the commands page, here are some examples:

  • /resident set perm {on/off} - This turns on or off all permissions for all perm-types and all perm-groups.
  • /resident set perm friend {on/off} - This turns on or off all permissions for the resident's friend list.
  • /resident set perm ally {on/off} - This turns on or off all permissions for all perm-types to the resident's ally list. This consists of the nation's fellow towns and their nation's allied nations.
  • /resident set perm outsider switch {on/off} - This turns on or off permissions for switch use by outsiders.

Lastly, don't forget those are just the defaults for plots, any owned plot can be set with it's own individual perms:

  • /plot set perm {on/of} - This turns on or off all permissions for all perm-types and all perm-groups on the plot which is being stood in.
  • /plot set perm friend {on/off} - This turns on or off all permissions for the resident's friend list on the plot which is being stood in.
  • /plot set perm ally {on/off} - This turns on or off all permissions for all perm-types to the resident's ally list. This consists of the nation's fellow towns and their nation's allied nations. This affects the plot which is being stood in.
  • /plot set perm outsider switch {on/off} - This turns on or off permissions for switch use by outsiders on the plot which is being stood in.

Mayors can changed the protection of their town with the following commands:

  • /town toggle explosion
  • /town toggle fire
  • /town toggle pvp
  • /town toggle mobs

Mayors and Residents can change each of their plots individually using these commands:

  • /plot toggle explosion
  • /plot toggle fire
  • /plot toggle pvp
  • /plot toggle mobs

Explosion and fire toggles are overridden by a mayor's town toggles. The preceding commands by themselves will change the perm line seen from /town or /res. They will also change any plots that were using the previously-set default perm line (town-owned or player-owned plots.) They will not change plots which were not set to the default perm line see in /town or /res. In order to change all plots a mayor or resident must use the following command, which will propagate the current perm line seen in /town or /res to ALL plots owned by the town or resident.

  • /res set perm reset - Propagates the perm line in /res to ALL plots owned by that resident.
  • /town set perm reset - Propagates the perm line in /town to ALL town-owned plots owned by that town.
  • These commands also affect the /town toggle and /plot toggle settings.

Setting trusted lists and plot perm overrides

As of Towny 0.97.1.0 there are Trusted lists for plots and towns, and plot's can have very fine-grained overrides set up. These features allow players to let other players work in towns and plots while not having to be restricted by the Friend/Resident/Town/Nation/Ally/Outsider plotgroups.

Towns may add a player as a trusted person in their town using /town trust add {name}, and remove them from the trusted list using /town trust remove {name}. Trusted players are treated similar to the mayor in all of the town's plots, able to do any build/destroy/switch/itemuse action.

A player may add or remove another player as trusted in their plots using /plot trust add|remove {name}. While a player is trusted in a plot, they have the same plot permissions as the plot owner, able to do any build/destroy/switch/itemuse action.

Plot perm overrides lets a player make very specific changes to how specific players are able to use plots. To begin a player is added or removed from a plot's perm overrides using /plot perm add|remove {name}. After a player is on this list, the plot owner can use /plot perm gui to open a GUI showing an inventory of player heads (the players who've been added to the plot perm override with /plot perm add {name}.) When a head is clicked on, a new inventory will display the options for Build/Destroy/Switch/ItemUse and a clickable book which explains how the rest of the system works. Players on the perm overrides list will have specific build/destroy/switch/itemuse permissions in the plot, overriding any other plot perm settings.

As of Towny 0.98.5.0 there is the ability to use /t trusttown add {townname}, which would make an entire Town's residentslist "trusted" by your town. This means that anyone in the 2nd town can do any build/destroy/switch/itemuse as if they were a mayor in the first town. Obviously this should only be given out under very limited circumstances, anyone added to the 2nd town after trust is given will also have full plot perm rights in the first town. There is a confirmation warning the player that uses the /t trusttown add command.

As of Towny 0.100.2.0 you can choose whether Town-Trusted players are able to use personally-owned town land as well. This is configured at global_town_settings.do_trusted_players_get_full_perms_in_personally_owned_land in the config.yml. When true any trusted players will get permissions in town owned land, and the personally-owned land in that town. When false, trusted players get permissions only in the town-owned land, leaving player-owned plots to their normal plot perms.

Protection Additions Found in Towny Advanced

New in Towny Advanced (0.72+) are three new protection types, anti-explosion and anti-firespread and piston-protection. On the town level, a mayor can set these flags using:

  • /town toggle explosion
  • /town toggle fire

Explosion protection stops all explosions. This stops TNT, TNT cannons and creeper explosions. Firespread protection stops all fires from spreading, including lava, lightning and lighters. Piston-protection allows pistons to operate between similarly owned townblocks or wild areas.

As of 0.95.0.0 Animal Luring (drawing animals' attention using their preferred food,) is controlled in the following fashion: In town-owned plots and in the wilderness, luring is not stopped. In personally-owned resident plots, the player must be able to break dirt in the plot to lure an animal.

As of 0.95.1.0 Villagers are protected from evil-doers.

As of 0.96.2.0 Lighting Nether Portals will now require a player to place Portal Blocks. This means that servers who want players to be able to make nether portals to a world where they do not grant towny.wild permissions will be able to build a portal. The node required to build a portal that would connect into the wilderness would be towny.wild.build.NETHER_PORTAL. This means servers that do not grant wild permissions do not have to give towny.wild.build.OBSIDIAN, which would mean players could place obsidian anywhere in the wild.

As of 0.97.3.0 Towny can provide a period of invulnerability from PVP combat when a player respawns. This is set in the config.yml at global_town_settings.respawn_protection.

How Towny Controls PVP Combat

Towny affects PVP combat, deciding who can be damaged where and by whom.

Plots, Towns and Worlds all have PVP settings, here is how they work.

World PVP Settings

World settings for PVP are controlled using in-game commands

  • /townyworld toggle pvp
    • This command disables and enables PVP world-wide. If you type /tw you will see will see a red {PVP} next to the name of the world at the top of the output. If PVP is off in the world, no pvp combat can occur, even in Arena plots.
  • /townyworld toggle forcepvp
    • This command forces pvp on world-wide, disregarding any plot or town pvp settings. Friendly-fire is still obeyed.
    • As of Towny 0.93.0.0 there is a new config.yml option at global_town_settings.homeblocks_prevent_forcepvp which can be enabled to stop forcepvp from affecting town homeblocks.
    • There is a way to override forcing pvp on in towns. Using /ta town {townname} toggle forcepvp you can override the forcepvp setting. This is useful for forcing pvp on worldwide but leaving it off in a spawn-town.
  • /townyworld toggle friendlyfire
    • This command toggles friendly fire on and off per-world. By default Towny disables friendly-fire between townmembers, nationmembers and residents whose nation considers the attacker's nations an ally.

Town PVP Settings

Towns pvp settings are controlled using this in-game command

  • /town toggle pvp - This toggles pvp on and off town-wide.

Additionally, admins have /ta town {townname} toggle forcepvp which will set a town's secret AdminEnabledPVP setting to true or false.

Plot PVP Settings

Plots can have their pvp status controlled individually with this in-game command

  • /plot toggle pvp - This toggles a single plot's pvp status.

Money

If you do not want Towny to have anything to do with money you can set using_economy: false in the config.yml and no taxes/upkeep will occur, and no claiming or town/nation creation will cost money.

There are settings for prices in the Economy section of the config file. The most basic settings are found in the new_expand section including:

  • price_new_nation: the cost of creating a nation.
  • price_new_town: the cost of creating a town.
  • price_claim_townblock: the base price of claiming a townblock using /t claim.

Taxes and Upkeep

Taxes and Upkeep are two separate functions with to different results. using_economy: true must be set in config.yml in order for Taxes and Upkeep to be applied. Taxes and Upkeep are charged at the same time, each 'Towny Day' or each time an admin uses the /townyadmin newday command. The time of a 'Towny Day' can be set in config.yml at day_interval: 1d and by default is 24 real-life hours. Any one can check how long until the next day starts by using /towny time.

The config.yml has an entry to turn taxation and upkeep on or off at daily_taxes: true.

Taxes

Taxes are collected on the town level from residents and on the nation level from towns. Any player can check the taxes which apply to them with the in-game command /res tax. Town mayors can use two commands to set their tax-rates.

  • /town set taxes {$}
    • This can be either a flat rate (ex: 10) or a percentage.
      • Toggling taxes from flatrate to percentage is done using /town toggle taxpercent.
      • Flatrate:
        • This charges each resident of a town the same amount. Setting it to 10 would charge each resident each 'Towny Day'.
        • If a resident can't pay his town tax when using flatrate taxation then he is kicked from the town.
        • This has a maximum amount which can be set in the config at economy.daily_taxes.max_town_tax_amount.
      • Percentage:
        • This charges a player a percentage of their money. If a player has no money left, he pays no taxes and is not kicked from the town.
        • A maximum amount taken by the taxpercent can be configured per-town using /town set taxpercentcap {$}.
        • This has a maximum amount which can be set in the config at economy.daily_taxes.max_town_tax_percent.
  • /town set plottax {$}
    • This charges each resident of a town for each plot they own. Setting it to 10 would charge Miner Steve 40 dollars if he owned 4 plots.
    • If a resident can't pay his plot tax he loses his plot.
    • This has a maximum amount which can be set in the config at economy.daily_taxes.max_plot_tax_amount.

As of Towny 0.99.6.0 mayors also have the ability to exempt their plots which are personally-owned (owned by a player,) from charging the normal plottax. This is done using /plot toggle taxed and prevents that plot from charging tax for ownership.

Nation leaders can use 2 command to set taxes on their towns.

  • /nation set taxes {$}

    • This can be either a flat rate (ex: 10) or a percentage.
      • Toggling taxes from flatrate to percentage is done using /nation toggle taxpercent.
      • Flatrate: - This charges each town that is a member of the nation. Setting it to 100 would charge each town's townbank 100 each 'Towny Day'.
        • If a town can't pay it's tax then it is kicked from the nation.
        • This has maximum amounts which can be set in the config at economy.daily_taxes.max_town_tax_percent and economy.daily_taxes.max_nation_tax_amount.
      • Percentage:
        • This charges a town within the nation a percentage of their money. If a town has no money left, they pay no taxes and are not kicked from the nation.
        • A maximum amount taken by the taxpercent can be configured per-nation using /nation set taxpercentcap {$}.
        • This has maximum amounts which can be set in the config at economy.daily_taxes.max_nation_tax_percent and economy.daily_taxes.max_nation_tax_percent_amount.

  • /nation set conqueredtax {$}

    • This tax is charged daily on the nation's towns which have the Conquered status, something gained from losing in a war.
    • Failure to pay can place a town into bankruptcy (if bankruptcy is enabled.)
    • A nation's default conquered tax, and maximum conquered tax can be configured in the config.yml at the nation.default_taxes.default_nation_conquered_tax and nation.default_taxes.max_nation_conquered_tax settings.

Admins can set options in the config.yml for controlling maximum/minimum tax amounts on towns. The above max_town|nation|plot_tax_amount options default to 1000 and max_town_tax_percent & max_nation_tax_percent which default to 25%. Which one is used depends on how the town is taxing, a flat rate or by percentage. town.default_taxes.minimumtax sets the minimum tax required when mayors use the '/t set taxes' command. nation.default_taxes.minimumtax sets the minimum tax required when nation leaders use the '/n set taxes' command. There are also settings for default taxes in new nations and new towns which can set default plottax, embassy taxes, shop taxes.

How to pay set a negative town and nation tax

As of Towny 0.99.6.0 it is not possible for towns and nations to set a negative tax rate, resulting in town tax being paid to town members, and nation tax being paid to the nation's towns.

In the config.yml at economy.daily_taxes.allow_negative_town_tax you can enable the ability for a town to set their tax below zero, resulting in the town paying the residents if it can. Likewise at economy.daily_taxes.allow_negative_nation_tax you can enabled whether a nation can set a tax rate below zero, which will result in the nation paying their towns, if it can.

How to pay landowners

A new option added to post-0.78.0.0 versions of Towny allows you to pay players money each day, based on the number of plots they own. To use this do the following:

  • Set a negative town upkeep and enable use_plot_payments: true in the config.yml
  • At a new day the negative upkeep will be used to calculate the towns upkeep, but instead of taking it from the town, it will be divided between the plot owners.
  • These funds are paid by the server, not the town.

Upkeep

Upkeep collection can be set on towns and on nations separately. Upkeep money is taken from townbanks and nationbanks and removed from the game. You can set the upkeep amounts to negative numbers to pay towns and nations instead of charging them. Upkeep is used by a server admin to remove inactive towns and nations from the server, it will also help reduce inflation in a server economy. Setting the upkeep to a negative number gives the town or nation-banks that amount each new day. Upkeep is set in config.yml with two flags:

  • price_nation_upkeep: 100.0
    • The server's daily charge on each nation. If a nation fails to pay this upkeep, all of it's member towns are kicked and the Nation is removed.
  • price_town_upkeep: 10.0
    • The server's daily charge on each town. If a town fails to pay this upkeep, all of it's residents are kicked and the town is removed.

Upkeep can be modified in the config.yml to affect different-sized towns differently. There are two ways to calculate the upkeep using the upkeep modifier found in the town_level and nation_level lines. By default the town_level and nation_level lines use the resident-count to determine upkeep via the upkeep modifier. The other option is to base it off plot-count rather than resident count. If you would like to set it based on plot-count set town_plotbased_upkeep:true in your config.yml. When plotbased_upkeep is used you can set minimum and maximum amounts that will be charged. More information on the townLevel line and how to configure it is here.

As of 0.95.0.0 you may now charge nations upkeep per-town at economy.daily_taxes.nation_pertown_upkeep. Uses total number of towns in the nation to determine upkeep instead of nation level (Number of Residents), calculated by (number of towns in nation X price_nation_upkeep). If economy.daily_taxes.nation_pertown_upkeep_affected_by_nation_level_modifier is true, the nation levels upkeep modifier will have an affect.

As of 0.95.0.0 you may now penalize towns which have claimed more townblocks than they are allowed. By setting price_town_overclaimed_upkeep_penalty_plotbased to true and putting an amount at economy.daily_taxes.price_town_overclaimed_upkeep_penalty towns will be charged this amount per townblock they are overclaimed by, in addition to their normal upkeep.

As of 0.97.3.0 a nation can be charged upkeep per-plot, using the economy.daily_taxes.nation_perplot_upkeep setting. This uses the total number of plots which a nation has across all of its towns to determine upkeep instead of nation_pertown_upkeep and instead of nation level (number of residents.) Calculated by (price_nation_upkeep X number of plots owned by the nation's towns.)

Admins can exempt a town from paying upkeep two ways:

  • Towns with NPC mayors (/ta set mayor TOWNNAME npc) do not pay upkeep.
  • Admins can use /ta town TOWNNAME toggle upkeep to exempt a non-NPC mayor town from upkeep.

Town and Nation Banks

Towns and Nations both have banks, to which any resident can deposit money but only town mayors and nation leaders (and assistants) can withdraw from. Any money collected via taxes is deposited to the nation/town bank. When a town needs money, to claim a townblock or an outpost, it is taken from the townbank. Since mayors and nation leaders can deposit money to their respective banks, some servers will find that mayors and nation leaders shield their wealth from plugins that take a players money for dying from pvp combat. To prevent townbanks from being exploited an admin can use two options:

  • Admins can set a cap on a town/nation banks at town_bank_cap and nation_bank_cap in the config.yml.
  • Admins can use '/ta toggle withdraw' to prevent mayors and nation leaders from removing money from their bank.

As of Towny 0.82.0.0 and on-wards the cap on banks is a hard cap and does not allow any money to be added to the town/nation banks if it would put the bank over the limit. This does not remove money from town/nation banks which are already over the limit.

As of Towny 0.96.6.0 there are bank history commands which open book GUIs showing transactions made to and from the town and nation banks:

  - /town bankhistory {pages}
  - /nation bankhistory {pages}
  - /ta town {townname} bankhistory {pages}
  - /ta nation {nationname} bankhistory {pages}

As of Towny 0.98.5.0 the ability to use /t deposit {$} {townname} to deposit into other towns has been added. This requires the server admin to give the permission node towny.command.town.deposit.othertown in the townyperms.yml file, this permission node is not given by default.

Admins can deposit/withdraw from town banks using /ta town {townname} deposit|withdraw {$} and from nation banks using /ta nation {nationname} deposit|withdraw {$}.

Town Bankruptcy

As of Towny 0.96.3.0, Towny has an optional bankruptcy feature which can be enabled in the config.yml by setting economy.bankruptcy.enabled: true. When enabled a town can have their bank go into a negative balance via paying upkeep and/or paying their nation's tax.

Towns that are bankrupt can use /t deposit {amount} to deposit money into the bank to pay back and remove the bankrupt status.

While bankrupt:

  • Towns cannot invite members.
  • Towns cannot set their town to open status.
  • Towns cannot claim more land.
  • Towns cannot have anything built in their land.

Debt Caps

How far a town can go into debt is up to the admin's discretion, but by default Towny will use the following formula to determine how much a town's debt-cap will be:

(Town Cost) + ((TownBlocks - 1)* Townblock Claim Cost) + (Outposts * (Outpost Cost - Townblock Claim Cost))

This roughly amounts to what the Town has had to spend to get to their current claims. The debt cap can be seen in the /town status screen.

This can be overriden in multiple ways:

  1. economy.bankruptcy.debt_cap.maximum : When set to greater than 0.0, this will be used to determine every town''s maximum debt, overriding the above calculation if the calculation would be larger than the set maximum.

  2. economy.bankruptcy.debt_cap.override : When set to greater than 0.0, this setting will override all other debt calculations and maximums, making all towns have the same debt cap.

  3. economy.bankruptcy.debt_cap.debt_cap_uses_town_levels: true : When true the debt_cap.override price will be multiplied by the debtCapModifier in the town_level section of the config. (Ex: debtCapModifier of 3.0 and debt_cap.override of 1000.0 would set a debtcap of 3.0 x 1000 = 3000.)

Alternatively there is a second way that debt caps can be calculated, as of Towny 0.99.3.0:

  • In the config.yml is a debt_cap_uses_fixed_days setting, that when set to true will cause a town to have a debt cap of exactly their daily upkeep cost multiplied by the economy.bankruptcy.debt_cap.allowed_days value, (default 7 days.)
  • When paired with the delete_towns_that_reach_debt_cap option in the config, towns will be fully deleted in a pre-determined time frame.
  • This alternate system is good for servers that want to see bankrupt towns disappear in a predictable time frame. With the original system very large towns that have turned into ghost towns can sometimes take a long time to hit their debt cap and become deleted.

Other bankruptcy rules

When economy.bankruptcy.upkeep.delete_towns_that_reach_debt_cap is set to true a Town that hits their debt cap will be deleted. If it is false they will not be deleted, but not go further into debt.

When economy.bankruptcy.nation_tax.do_bankrupt_towns_pay_nation_tax is set to true a Town will pay their nation tax out of their debt up to the point they hit their debt cap. If false towns that are bankrupt will not pay any nation tax and will leave their nation. True is recommended when using a Siege War style war/conquering system, otherwise conquered towns will be able to leave the nation simply by not paying the nation tax. False is recommended otherwise so that nations are not using abandoned towns to gather taxes.

When economy.bankruptcy.nation_tax.kick_towns_that_reach_debt_cap is true a Town that has hit their debt cap will be kicked from the nation for not being able to pay their tax.

Town Ruins

Added in Towny 0.96.6.0, the Town Ruins feature enables deleted Towns to enter into a pseudo-deleted state. It is enabled in the config.yml in the Town Ruining section. Simply put: when a town would be deleted, be it from not paying the upkeep, or someone using the delete command, the town becomes Ruined. After the configured amount of time set at town_ruining.town_ruins.max_duration_hours the town will become fully deleted.

While ruined a town is subject to the following:

  • The townblocks cannot be claimed by other towns (they are still claimed by the town,)
  • The town will be placed under the control of an NPC mayor,
  • The town can be griefed,
  • The town's residents will not be able to execute most /town commands and no /plot commands,
    • /town, /town reclaim|list|leave are allowed.

Town ruining is a useful method of preventing conquered towns from escaping their Nation by deleting their town and immediately and reclaiming their land under a new town. Town ruining was originally developed by Goosius for SiegeWar.

As of Towny 0.99.1.0 you can cause the town's remaining bank balance to be sent to the nation bank. This is disabled by default but can be enabled in the config.yml at town_ruining.town_ruins.town_bank_is_sent_to_nation.

As of Towny 0.100.2.0 ruined towns can slowly open up their plot permissions. This is enabled at town_ruining.town_ruins.do_plots_permissions_change_to_allow_all in the config.yml. If this is true, when a town becomes a ruin, every hour more and more of their plots will have their permissions turned to allow build, destroy, switch, itemuse to on. This will affect the newest claims first and progress until the first claims made are opened up right before the max_duration_hours have passed. When a town has more claims than max_duration_hours, multiple plots will be opened up each hour, ie: 500 claims and 72 max hours = 7 claims per hour. If a Town has less claims than max_duration hours, those claims' permissions are opened up much more slowly with hours passing between plots opening up, ie: 36 claims and 72 max hours = 1 claim every 2 hours. This system is meant to give players across many time zones the chance to loot a town when it falls into ruin.

Town Reclaiming

Town reclaiming is enabled in the config.yml at town_ruining.town_ruins.reclaim_enabled. When enabled any town member will be able to use the /town reclaim command in order to become the town's new mayor. This command will cost money, which is configured at economy.new_expand.price_reclaim_ruined_town and can be seen in the /towny prices screen.

Town reclamation can be limited to only be allowed after an amount of time has passed, configured at town_ruining.town_ruins.min_duration_hours which by default is set to 4 hours.

Town Conquering

Towns can become conquered by other plugins. When a town is conquered they cannot leave their nation (which is who they are conquered by.) Conquering can last forever, or it can be something which lasts for a pre-determined number of days. If it is set to a number of days, every time there is a Towny new day (when taxes are taken,) the conquered towns' conquered-days is reduced by one day. When the number of days has been reduced to zero, on the next new day the towns which are conquered become unconquered, and are once again able to use /nation leave to leave the nation.

While a town is conquered the town cannot leave their nation and they could be subject to an added nation conquered tax (if the nation has decided to use it.)

Towns become conquered by other plugins which use the Towny API. Plugins known to conquer towns are SiegeWar and EventWar.

Towny War

There are a number of war systems available as add-ons to Towny, check them out at the War Hub.

Chat

PlaceHolderAPI Support

PlaceholderAPI placeholders that Towny provides are link on this wiki page.

Townychat.jar

If you want Towny’s variables in chat, or the town/nation channels, you must download and install TownyChat.jar.

Using TownyChat with Other Chat Plugins

To use Towny and another Chat plugin follow these instructions:

  • Go into the Towny ChatConfig.yml and locate: modify_chat.enable: and be sure to set it to false like this: modify_chat.enable: 'false'
  • This will make it so that any GLOBAL type channel in the channels.yml is not modified by Towny, leaving it up to another chat plugin to modify its appearance.

Using TownyChat Without Another Chat Plugin

To use Towny as your sole chat plugin follow these instructions:

  • Go into the Towny ChatConfig.yml and locate: modify_chat.enable: and be sure to set it to true like this: modify_chat.enable: 'true'
  • Configure the chat lines using the information found in the section below.

Chatconfig.yml

The first config file for Towny's chat is the ChatConfig.yml found in the \plugins\towny\settings\ folder.

Towny chat formats

These are the pieces which can be used to make the Channel_format lines.

  {worldname} - Displays the world the player is currently in.
  
  {town} - Displays town name if a member of a town.
  {townformatted} - Displays town name (if a member of a town) using tag_format.town.
  {towntag} - Displays the formated town tag (if a member of a town) using modify_chat.tag_format.town.
  {towntagoverride} - Displays the formated town tag (if a member of a town and present) or falls back to the full name (using modify_chat.tag_format.town).
   
  {nation} - Displays nation name if a member of a nation.
  {nationformatted} - Displays nation name (if a member of a nation) using tag_format.town.
  {nationtag} - Displays the formated nation tag (if a member of a nation) using modify_chat.tag_format.nation.
  {nationtagoverride} - Displays the formated nation tag (if a member of a nation and present) or falls back to the full name (using modify_chat.tag_format.nation).
   
  {townytag} - Displays the formated town/nation tag as specified in modify_chat.tag_format.both.
  {townyformatted} - Displays the formated full town/nation names as specified in modify_chat.tag_format.both.
  {townytagoverride} - Displays the formated town/nation tag (if present) or falls back to the full names (using modify_chat.tag_format.both).
   
  {title} - Towny resident Title
  {surname} - Towny resident surname
  {townynameprefix} - Towny name prefix taken from the townLevel/nationLevels
  {townynamepostfix} - Towny name postfix taken from the townLevel/nationLevels.
  {townyprefix} - Towny resident title, or townynameprefix if no title exists
  {townypostfix} - Towny resident surname, or townynamepostfix if no surname exists
   
  {townycolor} - Towny name colour for nation leader/mayor/resident
  {group} - Players group name pulled from your permissions plugin
  {permprefix} - Permission group prefix
  {permsuffix} - Permission group suffix.
  {permuserprefix} - Permission group prefix
  {permusersuffix} - Permission group suffix.
   
  {playername} - Default player name.
  {modplayername} - Modified player name (use if Towny is over writing some other plugins changes).
  {msg} - The message sent.

  {channelTag} - Defined in the channels entry in Channels.yml
  {msgcolour} - Defined in the channels entry in Channels.yml

Message spam control is set at spam_time: 0.5 The channel_formats section determines what each chat channel will look like. The tag_formats section determines what the tags will appear as. The colour section determines colours applied with {townycolor} for mayors, nation leaders and residents. The modify_chat section is where you can disable all chat additions from Towny. You can also set per_world to true if you'd like to use the worlds: section to change chat lines' channels on a per-world basis.

Chat Channels

Chat Channels are set in Channels.yml found at \plugins\towny\settings\Channels.yml There are six chat channels by default in Towny, although an admin can create as many chat channels as they'd like in Channels.yml. Channels.yml allows you to set commands for joining and using each channel:

  • /g
    • Put in from of text to speak in general/global chat, or without text afterwards to enter the channel.
  • /l or /lc
    • Put in from of text to speak in local chat, or without text afterwards to enter the channel.
  • /tc
    • Put in from of text to speak with members of your town only, or without text afterwards to enter the channel.
  • /nc
    • Put in from of text to speak with members of your nation only, or without text afterwards to enter the channel.
  • /ac
    • Put in from of text to speak with all members of your nation as well as any member of a nation you are allied with, or without text afterwards to enter the channel.
  • /a or /admin
    • Put in from of text to speak in adminchat, or without text afterwards to enter the channel.
  • /m or /mod
    • Put in from of text to speak in modchat, or without text afterwards to enter the channel.

The tags for each channel can be set, these are used in the ChatConfig.yml for {channelTag}. Permission nodes for each channel can be set. Ranges for each channel can be set:

  • -1 = no limits
  • 0 = same world only
  • any positive value = limited range in the same world.

Putting players into channels on join

Using the info|option|meta nodes provided by GroupManger, PEX and bPermissions it is possible to put users into chat channels upon joining the server. In the same section as prefix: and suffix: add a node towny_default_modes: '' Possible channels are general, town, nation, admin, mod and local. Example in group manager:

                groups:
                  Default:
                    default: true
                    permissions:
                    - general.spawn
                    inheritance: []
                    info:
                      prefix: ''
                      build: true
                      suffix: ''
                      towny_maxplots: 1
                      towny_default_modes: 'local'
                  Admins:
                    default: false
                    permissions:
                    - '*'
                    inheritance:
                    info:
                      prefix: ''
                      build: true
                      suffix: ''
                      towny_maxplots: -1  
                      towny_default_modes: 'admin'

Towny titles and surnames

Leaders of nations can use two commands to change the displayed chat names of their minions:

  • /nation set title {resident} {text of prefix}
    • Adds a prefix to the player.
  • /nation set surname {resident} {text of suffix}
    • Adds a suffix to the player.
  • A title/surname given to a mayor will override the MayorPrefix/MayorPostfix set in the townLevels of the config. He will still retain the colouring set on mayor names (default is light blue.)

Mayors of towns can use two commands to change the displayed chat names of their minions:

  • /town set title {resident} {text of prefix}
    • Adds a prefix to the player.
  • /town set surname {resident} {text of suffix}
    • Adds a suffix to the player.
  • A title/surname given to a mayor will override the MayorPrefix/MayorPostfix set in the townLevels of the config. He will still retain the colouring set on mayor names (default is light blue.)

If you would like to prevent titles and surnames from allowing colour codes you need to edit the config.yml's regex setting: name_remove_regex: '[^\P{M}a-zA-Z0-9\&._\[\]-]' to look like this: name_remove_regex: '[^\P{M}a-zA-Z0-9._\[\]-]', doing so will prevent players using the & (and thus stopping colour codes being added.)

Optionally, you can allow colour codes via the regex and still configure whether a mayor or nation leader is allowed to use colour codes via a permission node. This must be enabled in the config.yml at filters_colour_chat.modify_chat.does_adding_colour_codes_require_permission_node. When true, a mayor or nation leader will need the permission node in order to add colour codes to residents' titles and surtitles. Nation leaders require towny.command.nation.set.title.colours, mayors require towny.command.town.set.title.colours. These nodes are not given out by the default townyperms.yml and must be added to the mayor and king section when this setting has been made true.

Spying on chat channels

Admins can spy on all chat channels by using the command /towny spy or /res set mode spy. Any player can be given the ability to spy by being given the permission node towny.chat.spy

Multiworld

Towny has mutliworld support. Each world has a datafile located at \plugins\towny\data\worlds\worldname.txt and each world is listed in \towny\data\worlds.txt.

World Toggles

Towny can be turned off in a world in-game. While standing in a world type /townyworld toggle usingtowny. Other toggles:

  • usingtowny - Turns towny off in a world.

  • claimable - Whether townblocks can be claimed by mayors in this world.

  • pvp - Whether PVP is on in the world.

  • forcepvp - Used to force pvp on in towns.

  • friendlyfire - Used to turn friendlyfire on or off.

  • explosion - Used to toggle explosions off/on in the wilderness.

  • forceexplsion - Used to force explosions on in towns.

  • fire - Used to toggle fire off/on in the wilderness.

  • forcefire - Used to force firespread on in towns.

  • townmobs - Used to turn off mobremoval in all towns. Restricted mobs are listed in the config.yml at town_mob_removal_entities.

  • worldmobs - Toggles mobremoval over the entire world. Restricted mobs are listed in the config.yml at world_mob_removal_entities.

  • wildernessmobs - Toggles mobremoval in the wilderness. Restricted mobs are listed in the config.yml at wilderness_mob_removal_entities.

  • revertunclaim - toggles the revert-on-unclaim setting for that world.

  • revertentityexpl - toggles the revert-on-explosion (caused by entity explosions) in the wilderness setting for that world.

  • revertblockexpl - toggles the revert-on-explosion (caused by block explosions) in the wilderness setting for that world.

  • plotcleardelete - toggles the ability of players to use /plot clear in plots they own.

  • unclaimblockdelete {on|off} - Turns on/off the delete-blocks-on-unclaim feature in the world.

  • warallowed - toggles whether event war is allowed in the world.

  • wildernessuse - toggles whether players can build/destroy/switch/itemuse in the wilderness.

Permission Nodes

Towny has a permission plugin built-in, called TownyPerms. This system is configured in the towny\settings\townyperms.yml file. Permission nodes are given out based on a player's role.

Towny will give out these permission nodes to all players based on their roles and ranks, as long as they are in a world with Towny turned on.

If you're going to have a resource world with no claims, instead of turning Towny off in the world (using /tw toggle usingtowny,) make the world unclaimable (using /tw toggle claimable.) This will ensure that player will still receive permissions from TownyPerms while being unable to claim land in your resource world(s).

If you're curious about what permission nodes are part of TownyPerms you can check out the Permission Nodes wiki page.

Configuring Townyperms.yml and the Roles of the Ranks Within

This system pushes permissions directly to Bukkit and works along side all other perms plugins. It allows you to define sets of permissions based upon a players status (nomad/resident/mayor/king). You can also assign additional permissions based upon any assigned town/nation ranks (assistant/vip etc). This system is not limited to Towny permission nodes. You can assign any permissions for any plugins in its groups. This file allows admins to decide what each player-rank can do. Some ranks are assigned automatically:

  • Players without towns are Nomads.
  • Players in towns are Residents.
  • Owners of towns are Mayors.
  • Owners of nations are Kings.

Some ranks are assigned by Mayors or Kings, and supplement the ranks the players already have:

  • Mayors can make a resident a Town Assistant.
  • Kings can make a resident a Nation Assistant.
  • Mayors and kings can grant admin-created ranks, allowing for diverse customization.
    • A player can attain many Supplemental ranks from their mayor or king, allowing for diverse nation/town-roles.
    • Examples of this would be town-builders, town-bankers, nation-bankers, town-inviters, etc.

A resident of a town can see the ranks within their town using /town ranklist. A mayor can use /town rank {add|remove} {playername} {rankname} to give a player a new rank within their town. A king can use /nation rank {add|remove} {playername} {rankname} to give a player a new rank within their nation.

As of Towny 0.97.1.0 admins are able to edit the townyperms.yml ingame using the /ta townyperms command. See /ta townyperms ? for commands and information.

As of Towny 0.99.1.0 admins are able to assign priorities to Town and Nation ranks, allowing a prefix to be set for ranked players. The Town and Nation ranks in the townyperms.yml can now be assigned two permission nodes:

  • towny.rankpriority.#
  • towny.rankprefix.

Ex: Assistant rank can be given:

  • towny.rankpriority.100
  • towny.rankprefix.&a&r The Sheriff rank can be given:
  • towny.rankpriority.500
  • towny.rankprefix.&b&r A player that has both the sheriff and assistant rank will show the assistant prefix using the below PAPI placeholder.

Multi Language

Towny has support multi-language support. Languages available can be found on the Crowdin page for TownyAdvanced. If you don't see your language available ask for it on the discord or in an issue ticket.

Towny uses the Minecraft game client's locale to determine which language Towny's messages will appear in, as long as it is one of the languages on our Crowdin page. This means that player's determine which Language they see Towny's messages in. The player sets their Minecraft Language, in their Minecraft Settings, and Towny reads what locale the client wants to see Towny using.

The server admin can select the default language in the config.yml's language: setting. This is the language that most console messages will appear in, as well as the language for players whose language is not natively supported.

Server admins can override the default language files in a number of ways:

  1. The towny\settings\lang\override\ folder contains one file by default, the global.yml. This file can have any of the Towny language strings added to it, and it will override every language. This is very useful for changing the Towny prefix, or the colours of the status screens.

  2. By moving files from the towny\settings\lang\reference\ folder into the towny\settings\lang\override\ folder an admin can override a single language at a time.

Important: Making any changes to the files in the towny\settings\lang\reference\ folder will have no effect in-game.

As of Towny 0.99.6.0 the entire command help menu system, usually found via /[townycommand] ? or help is now translatable!

Towny Regex Settings

Towny controls which characters are allowed to be used in town and nation names via the config.yml regex_settings.

The default settings are:

  regex:
    name_filter_regex: '[\\\/]'
    name_check_regex: ^[\p{L}a-zA-Z0-9._\[\]-]*$
    string_check_regex: ^[a-zA-Z0-9 \s._\[\]\#\?\!\@\$\%\^\&\*\-\,\*\(\)\{\}]*$
    name_remove_regex: '[^\P{M}a-zA-Z0-9\&._\[\]-]'

and allows for unicode (non-English) characters to be used.

There are some servers whose economy plugins cannot use unicode characters, or some times the server host's operating system will not let you save to the flatfile database with unicode characters. Or the server admin just doesn't want to have unicode characters in their town and nation names. These servers should use these regex settings instead:

  regex:
    name_filter_regex: '[\\\/]'
    name_check_regex: ^[a-zA-Z0-9._\[\]-]*$
    string_check_regex: ^[a-zA-Z0-9 \s._\[\]\#\?\!\@\$\%\^\&\*\-\,\*\(\)\{\}]*$
    name_remove_regex: '[^a-zA-Z0-9\&._\[\]-]'

As of Towny 0.97.2.0, Towny will automatically rename towns and nations which have characters which are not allowed by the regex. This solves the issue of your operating system not supporting characters when the town and nation files are saved. The renamed towns and nations are given very generic names.

If you would like to prevent titles and surnames from allowing colour codes you need to edit the config.yml's regex setting: name_remove_regex: '[^\P{M}a-zA-Z0-9\&._\[\]-]' to look like this: name_remove_regex: '[^\P{M}a-zA-Z0-9._\[\]-]', doing so will prevent players using the & (and thus stopping colour codes being added.)

Towny's Database

As of Towny 0.80.0.0 admins can choose to use an SQL database instead of flatfile.

Configuring MySQL

  • Open the \towny\settings\database.yml.
  • Navigate to the sql: section.
  • Configure towny with your mysql database hostname/port/username and password.
  • Set the desired mysql flags in the flags section.
  • Save the config and read below for conversion instructions.

Converting Flatfile to SQL

  1. Stop your server.

  2. Open the \towny\settings\database.yml.

  3. Find the database_load, make sure it's set to flatfile.

  4. Find the database_save, set it to mysql.

  5. Save the config and start your server.

  6. While your server is running:

    • Set the database_load to mysql.
    • Type /ta reload all ingame.

  7. Open the Towny\Data\ folder and remove all but the plot-block-data folder. This folder contains the plot-snapshots used in the revert-on-unclaim feature. If you do not use that feature you may delete the entire Towny\data\ folder.

  8. It is important to note that Towny does not back up the sql database. It is up to you to do this.

Converting SQL to Flatfile

  1. Stop your server.
  2. Open the \towny\settings\database.yml.
  3. Find the database_load, make sure it's set to mysql.
  4. Find the database_save, set it to flatfile
  5. Save the config and start your server.
  6. While your server is running:
    • Set the database_load to flatfile
    • Type /ta reload all ingame.

Towny Advanced

  • Home
  • FAQ
  • How Towny Works - Comprehensive guide for admins & players.
  • Video Tutorials - Watch and learn with Major Graft.
  • TownyAPI - Guide for plugin developers.
  • Discord - Get involved with other Towny Admins, Plugin Developers, Testers. Support, General Discussion welcome.

Setup

Support

Changelogs

Reference

Misc

Clone this wiki locally