Imagine this: A group of players bands together and purchases a large plot of land. They call in some favours and get help flattening the hills and digging out the underground, after which they construct a central castle themselves. Inside the castle they get shared areas and personal quarters, while plots outside the castle are sold to other players. Before long, an entire city forms on the land they claimed. Meanwhile, the server staff has just finished working on public railroads that traverse large sections of the world. And all this protected against griefing and creeper-explosions.
This, and more, is what Residence allows.
What is Residence?
Residence is a bukkit plugin that allows for players to protect their homes without admin intervention. It does this by letting players claim land, then configure settings that allow and disallow certain acts to be committed. It also has value for staff, since not only can the owner let them bypass Residence-restrictions, they can also turn places into server-property. This allows for things such as protected spawn cities, roads and railroads.
Meanwhile, by temporarily giving players permissions in protected land, the community can can aid server-projects. In VeteranCraft, Vetropolis' harbour was dug out in such a manner.
There are three ways for a server to run Residence. For free, with one-time fees or with repeated lease-costs. In VeteranCraft, you pay a single time. For most of the features it doesn't matter, though.
Sections of this Guide
The goal of this guide is to make the reader understand the different features Residence offers, so they can use the plugin to its full capabilities if so desired. To reach this goal, we step through one section at a time. The sections are:
- Res Limits, important limitations on the creation process
- How to select land for a residence
- Creating a residence and adding areas to one
- The Permissions-system, an important tool to Residence's flexibility
- A table of Permission Flags, with information on what each flag does
- The Subzone system, which allows one to have different permissions set in different parts of a home
- The Residence Market, which lets you buy and rent
- A list of special commands with occasional use
- An expert section covering more complicated tricks
- Commands List
It should be noted that this guide does not come from someone involved in the creation of the Residence plugin. Nor do I have experience running Residence serverside. This guide compiles personal experience into a guide for players, not server owners, to use Residence. While most of its information is useful for staff, this guide won’t handle the more complex settings and commands only available to admins.
Another thing to note is that this guide is primarily aimed at VeteranCraft. Other servers can have different default settings, no promises are made regarding those!
Now that we got the inevitable disclaimer out of the way, time for the guide to continue!
If the first step to Residences is selecting an area for one, step 0.5 would be "/res limits". The command will provide you with important intel on a server’s limits on Residence creation. The image below shows those of VeteranCraft.
|Permissions Group / Residence Group||One of these determines what the rest of these settings will be, server-owners can make it so that some people have different permissions and settings. What the other is for, I don’t know.|
|Residence Admin||If this is true, you can ignore permission limits. More on this in the Expert section.|
|Can Create Residences||If false, you can’t make residences.|
|Max Residences||Maximum number of Residences you can own.|
|Max East/West Size
Max North/South Size
Max Up/Down Size
|These decide how large a single selection is allowed to be. If your selection violates at least one of these size limits, you can’t create a new area.|
|Min/Max Protection Height||Default is from bedrock to the sky, but it’s possible for a server owner to disallow buildings below/above certain heights, as to not restrict mining and such.|
|Max Subzone Depth||Creating subzones in subzones allows for neat tricks covered in the Expert section.|
|Can Set Enter/Leave Messages||If true, you can change the messages a player gets when entering/leaving your residence.|
|Number of Residences you own||If this is less than the maximum number allowed, you can make a new one.|
|Residence Cost Per Block||How much each cube will cost you. In VeteranCraft it’s 7 cents, differs per server. With this value you can calculate in advance whether you can afford your dreamhouse.|
|Flag Permissions||I seriously haven’t got the faintest what this stands for.|
The first thing you should know about Residences is their structure. Residences exist of areas, where each area is a cuboid. Using the selection tool (in VeteranCraft this is a wooden sword) you left-click one corner and right-click the opposite corner. The entire area inbetween, up to and including the corners, is then your selection. In the example shown, selecting the two cobblestone cubes will select the entire structure.
There is a handful of "/res select …" commands that aid in the Selection process.
The first is "/res select size". This will tell you the X, Y and Z dimensions of your selection, as well as the total size (X*Y*Z) and the money it will cost to claim. The cost is always rounded up to the whole buck, so 1 block costs the same as 10.
While claiming is simply a matter of selecting two opposite corners, sometimes this isn’t viable. For example, you might want to claim a large chunk of ocean and would suffocate while trying to reach the bottom, or want to claim part of the sea and not want to damage the waterflow with placing a block. For this you can use the expand commands.
To use the expand option, simply look in a direction (up/down/north/south/east/west) and use "/res select expand [amount]". Negative numbers can be used to adjust for an overshoot. So say you want to raise the roof with 5, just look up and type "/res select expand 5".
Another useful expansion command is "/res select vert". This turns your selection to one ranging from sky to bedrock. While this may cost more, for admins and rich folks it can be a nice idea.
Unfortunately it’s not possible to check the coordinates of your selection’s corners, so make sure not to make any mistakes while expanding.
Selected areas are used for 3 different things: Creating a residence’s initial area, selecting additional areas to add to a residence, and creating subzones inside a residence. The first and second are up next.
Residence Creation & Addition
With your brand new central area selected, it’s now time to create a residence. This is done with "/res create [resname]" where resname is whatever you want to call the place. Since there is a good chance you’ll be typing this name quite a bit, and since capitalization matters, make sure to pick something easy and short here. "MrAwesomeHisAwesomeHouse" is an utter pain when you try to access five dozen elements of it.
However, a residence doesn’t have to be a single cuboid. In the default settings, a residence can be made of a max of 2 areas. In VeteranCraft it’s 100. Don’t ask. It originates from a mixup in Residence lingo and is a pretty long (read: embarassing) story. Basically you can add a second area to a residence, or in VeteranCraft you can combine dozens. That increased number is quite useful because it allows city-owners to save money.
A city can easily include deep cellars, high buildings, water sections, low roads and more, all sections you want to give different height and depth. A ship with huge sails can be much higher than any building in the city will be, but it’d be a waste to pay for all that unused air. And that’s when areas enter the game.
Rather than having 1 cuboid as a residence, you can stitch multiple cuboids together in 1 residence. They can overlap or be completely disjunct and even separated. Unfortunately you you still have to pay the full dime for any area, no matter how much of it overlaps with land that’s already yours.
When you want to add an area to a residence, you go through the same selection process. Then, rather than doing the same old "/res create …", you instead use "/res area add [resname] [areaname]". The name of the area isn’t that relevant, especially when it can be renamed, but since others can see those you might want to pick decent names. Or at the least pick names that still make sense to you after a week. By the way, the initial area made always is named "main".
It should be noted that while residences can clearly not overlap with others, areas within your residence are allowed to overlap with other areas within. Aside from the doublecharge issue, that can be quite useful. One more important detail is that the size-limits apply to each separate area. Separate areas may combined violate the bounds. In servers with limited areas that’s hardly relevant, in others it can be perfect for protecting long networks.
Permissions & Flags
The main part of Residence is that it lets you protect your buildings and possessions. You can disallow griefing, lock your chests and doors, disallow pvp and firespread, block tnt and creeper explosions, cancel monster spawns and a few more. Even better, you can give specific people rights to let friends help you with building your cathedral, while also giving them access to the shared storage the supplies are stored in. This all works with the permission system. There are three kinds of permission flags: general flags, group flags and individual flags. Group flags are the same as individual flags but set for groups instead. Since those won’t be used a lot, this guide will leave them out of the picture for now. The commands are:
- /res set [residence] [flag] [true/false/remove]
- /res gset [residence] [group] [flag] [true/false/remove]
- /res pset [residence] [person] [flag] [true/false/remove]
If you are standing inside the residence, you can leave out the residence name. e.g. /res set monsters false
A flag can be set to 3 values: True, False and Remove. The last one isn’t really a value but removes any previously set value, allowing more generic values to be used instead. The use for this is twofold. First off not cluttering the info list, second subzones inheritage as explained in the subzone section. When a flag is set to true or false for an individual, that value is applied. If no value is set, the general value will be used, and with that missing the default value applies. These depend on your server’s settings.
Some special notes:
- When a residence is made, a few default values will be set, as well as some pset for the owner. Which ones and at what values depends on your server’s settings. For example, in VeteranCraft those flags include -pvp, -creeper, -tnt, -container, -use, -build, while the owner gets +container, +use, +build.
- The command "/res tpset" lets one set a teleport point for "/res tp [residence]". If not used, a player will teleport to near the SW corner of the residence. Has to be manually set for each subzone, they do not use the general teleport point.
- Merely allowing spread or spawning does not mean it will happen. The other conditions, such as light, all still apply.
- Either the tnt or the creeper flag nullifies Ghast fireballs. Which of the flags it is this author does not know.
- Speaking of tnt and creepers, if they try to explode near a protected residence or subzone, they still won’t go off. Don’t place tnt near the border of a protected area or you might waste some. It also means creepers can’t harm you when you’re on the edge of a residence, even if they go off outside.
- When +piston is set, a player outside your residence can use pistons to add or extract blocks in your residence. Try avoiding setting this flag on true in main residences, only use it in subzones that aren’t adjacent to the outside of the residence.
There are two general types of flags. General flags that can only be set, and individual flags that can be both set and pset. The override-flags for build (place/destroy) and flow (lavaflow/waterflow) are left out of this list.
|Animals||Allows/disallows the spawning of passive animals. Also applies to Pig Spawners.|
|Creeper||If false, disallows creeper explosions in/near the residence. A creeper will just sizzle and disappear.|
|Damage||If true, disallows players from taking damage. Cannot be set by normal players in VeteranCraft.|
|Firespread||Allows/disallows the spreading of fire. If false, blocks won’t burn up but remain on fire.|
|Flow||Allows/disallows flowing of water and lava. The lavaflow and waterflow flags override this one.|
|Healing||If on, players heal an additional half heart per second. If off, normal mechanics apply.|
|Ignite||Allows/disallows the manual starting of fires.|
|Monsters||Allows/disallows all kinds of monster spawning. Monsters from the outside can still enter even with spawning off.|
|Piston||Allows/disallows usage of pistons. If false, pistons from inside and outside can’t work if at least 1 block would be part of, or be pushed into, the residence.|
|PvP||Allows/disallows the attacking of players and tamed wolves.|
|Spread||Allows/disallows the spread of grass and mycelium.|
|TNT||If false, TNT disappears without explosion when detonated in/near the residence.|
|Admin||Allows/disallows players to set flags. Not available as general flag. Cannot be set by normal players in VeteranCraft.|
|Bucket||Allows/disallows the usage of buckets.|
|Build||Allows/disallows placement and destruction of blocks. The place-flag and destroy-flags override this one.|
|Container||Allows/disallows access to objects with an inventory: Chests, Furnaces, Dispensers.|
|Move||Controls whether people can walk around in the residence. If disallowed, the game will stop them when they try.|
|Subzone||Allows/disallows the creation of subzones by a player or in general.|
|TP||If residence-teleporting is allowed for a player, this controls whether they can teleport to this specific residence. Is connected to “/res tpset” as described below.|
|Use||Allows/disallows usage of doors, levers, buttons, trapdoors. Pressureplates are not included and can always be used by anyone.|
The flags alone aren’t what makes Residence as strong a protection plugin as it is. Its true strength comes from the ability to create subzones, which are parts of a Residence with their own permission flags. A few uses of this are shared storage, publicly and privately accessable areas, railroad stations and temporary construction zones.
It’s very important to be familiar with the difference between areas and subzones. Areas are the physical ortions of claim land that combined make up a residence. Subzones are virtual zones inside a residence that are extensions to the right-system but carry no physical presence. Adding a subzone does not make a house bigger, it simply lets you define specific rooms. Also, subzones can be stretched over multiple physical areas of a residence.
To create a subzone, first select the area with the selection tool as explained before. Then, use the following command:
- /res subzone [resname] [subzonename]
After this, the subzone will be [resname].[subzonename]. For example, in my residence Capetown I have a Mall, which can be accessed with the resname Capetown.Mall. I could use "/res set Capetown.Mall use true" to let people open doors in it, or "/res set Capetown.Mall move false" to temporarily block all access while I reconstruct the place.
As mentioned before, when standing in a residence you can leave out the residence name from the set commands. When leaving out the name, the deepest subzone you are in will be changed. So when inside Capetown, commands will impact Capetown. Inside the general area of the Mall, Capetown.Mall will change. Inside a shop, for example F1_A, Capetown.Mall.F1_A will have its rights changed.
As for the flags of a residence, an inheritage system is used. First, the subzone is checked for a personal flag. If no true/false value is present, the next level is checked, and so on, until the main residence. If no personal value is found, group flags are checked in the same order, after that the general flags. If not a single level has the flag set to true or false, the default value of the server will be used.
Thus, if you do "/res set X.Y use true" and "/res pset X Jerk use false", the player Jerk cannot open doors in X.Y. After all, X.Y has no value set for Jerk, so then X is checked, which says "no way bro". If at any point you use "/res pset X Jerk use remove", no flag will be set for Jerk and the system will use the general flag set in X.Y instead.
This is, as refered to before, what the difference between false and remove means when getting rid of a flag. One screws you over in all subzones of the current zone, the other lets those subzones determine themselves what you are and aren’t allowed to do.
Subzones in subzones, as well as removing subzones, are described in the Expert section.
With subzones you can give people basic rights, such as build/use/container, to give them a room in your place. However, they are still fully dependant on you for setting additional rights as well as giving others rights. You also have to manually give them the rights, which with complex names can be an utter pain in the neck. If you want to avoid that hassle, you can sell or rent out the rooms instead, using the Residence Market. While technically this is possible with entire residences, chances are you’ll only use it for subzones. To keep things easy, this guide will not bother with marketing main residences.
When someone buys or rents a residence, or subzone of one, they receive full control over it. This means they can tear its contents down, build an atrocity and invite all the other punks to a pool party that keeps the neighbours up all night. On the bright side, you get money from it, which helps you earn back at least part of what the residence cost you. The easiest thing you can do is put a subzone up for sale. They can buy it and poof, you get the cash and they the subzone. The commands for that are below, but first the more complex part: Renting. Renting exists of 3 factors: The rent per period, the length of the period, and whether or not it can be rented for multiple periods at length. If someone decides to rent the place and it can be rented for multiple periods, they can decide for themselves whether they are willing to. And if they want to, they can cancel the contract and hand the subzone back over with a single command. No refunds of course.
In this commandlist, [residence] is the full naming. For example, "/res market sell Capetown.Mall.F1_A 1200"
|/res market sell [residence] [amount]||Puts a residence/subzone for sale for [amount]. Mistakingly tells you you sold X for Y when selling X.Y or X.Y.Z-, /res market info works just fine though.|
|/res market unsell [residence]||Use this to withdraw a residence/subzone from the market.|
|/res market buy [residence]||Use this to buy an available residence/subzone.|
|/res market rentable [residence] [cost] [days] <repeat:t/f>||Makes a residence/subzone rentable for a defined amount of days at a time, with the given cost per period. If repeat is on, it can be automatically rerented by the renter if they so desire.|
|/res market rent [residence] <repeat:t/f>||Rent a residence/subzone. Set repeat to true if you want to rerent when the rent period ends. Only possible if the landlord has allowed repeated renting.|
|/res market release [residence]||When a place is still on the market, the owner can use this to take it off the market. When someone is renting the place, they can use this to bail on it and hand it back to the owner.|
|/res market info [residence]||Provides you with the name and price of a residence/subzone, as well as its rental parameters if it’s a rental.|
One can browse the market, either by checking out the info of a specific residence/subzone, or by checking the list of everything for sale or rent. Unfortunately this list currently does not seem fond of whitespace, resulting in a string of symbols and dots without an easy way to see where one name ends and another begins. But there is one remedy: When inside a residence/subzone that’s for sale or rent, using the "/res market info" command without the name will give you the information regardless, including the name. So all that a city owner needs to do is for-sale signs and open doors, then a player can simply enter, check the place out with "/res info", check its price with "/res market info". If they want the place, they can then use the buy or rent command, whichever applies.
Mind you, one cannot control who may buy or rent a place. If you want a specific individual to obtain it, make sure to discuss it in private and have them have their finger on the trigger, to obtain it the very second you make it available. You could always give them a refund afterwards, to basically hand them the place for free.
There are two important details one must keep in mind when using the market:
- When you buy or rent a subzone, it does not count for your personal residences. Thus you can hire as many rooms as the other settings allow. Yes there are specific server settings, so make sure to double-check those.
- Just because you buy a subzone, doesn’t mean the rights inheritance system no longer applies. Any personal rights in the main residence or higher zones apply, unless you specifically oppose them. That means a city owner has a responsibility not to give others rights in the main residence, they’d have to use temporary construction subzones instead. It also means that if you can’t trust the owner, you shouldn’t get the place, since they can give anyone access to their residence and thus your house. It helps if your server keeps logs for blocks and chests. VeteranCraft does.
There are quite a few commands not listed in this guide, not all will be listed here. Nevertheless, this section will cover a few sets of commands not handled before. A side note: Some of these commands can, under certain conditions, be used without the residence name to apply to the zone you are currently located in. Others, however, cannot. Because of this, only the full versions are provided here.
It’s possible to get more info on the areas and subzones of a Residence with a few commands:
|/res area list [residence] #||Provides you with page # of a list of all areas of the residence. If no pagenumber is supplied, defaults to page 1.|
|/res area listall [residence] #||Same as list, but also includes the 2 corners that define each area, plus their sizes.|
|/res sublist [residence] #||Provides you with page # of a list of all subzones of the residence. If no pagenumber is supplied, defaults to page 1.|
You can use these commands on subzones, so for example "/res sublist X.Y". However, subzones always have only 1 area, which is created at the same time as the subzone and is identical to the subzone itself. Also, these subzone-areas do not count for the area-limit of the main residence.
One can rename and remove subzones, areas and entire residences. Removing a subzone won’t harm the residence, areas will. And don’t count on a refund.
|/res rename [oldname] [newname]||Renames a residence. When renaming a subzone, [oldname] must be the entire name (e.g. X.Y.Zold) but [newname] is just the new name (e.g. Znew).|
|/res renamearea [residence] [oldname] [newname]||Lets you rename physical areas. It’s possible to rename the one and only area of a subzone, which has the subzone name as original value, for appearance’s sake.|
|/res area remove [residence] [area]||Removes said area from the residence.|
|/res remove [residence]||Removes a residence entirely, or the existance (but not the physical part) of a subzone. See the Expert section on how removing subzones works.|
When entering/leaving a zone, you are usually greeted with a default message. These can be changed or removed entirely if so desired. Removing them can be quite useful in combination with LocalShops, since shops already have their own messages. When changing a message, you can use %player to show the name of the player, %residence to show the residence’s name (useful for if you macro the message) and %owner to show the owner’s name.
|/res message [residence] [enter/leave] [message]||Sets a enter/leave message of the entered residence.|
|/res message [residence] remove [enter/leave]||Removes any existing enter/leave message,|
|/res message [enter/leave] [message]||Same as above but in the deepest zone you are currently in.|
|/res message remove [enter/leave]||Same as above but in the deepest zone you are currently in.|
A minor note here is that when entering/leaving a subzone you are not greeted with messages of the parent zone. A subzone is, after all, still a part of the parent zone, so you never left that one.
A few special tricks will be discussed here, that can make things much easier on you if you use them well. Since they are not necessary to use residence properly, they were gathered in this last section.
If a usergroup is set as Residence Admin, they can deliberately bypass residence restrictions, allowing them to build/use/container without permission. They can also set flags and change other options, as long as they use "/resadmin" instead of "/res" to start the command. This is incredibly powerful, especially without proper logging mechanism, so be extremely careful with giving staff this capability. After all, it completely nullifies the protection that Residence offers.
Server Property & Owner Changes
Admins can remove the residences of players, change the owners of residences and hand residences over to the server itself, meaning only residence admins can modify it. My assumption is that serverland also doesn’t require lease costs when leasing is used. When changing the owner of a residence, a problem that arose in the past, which may still be present, is that the subzones didn’t change owner. This means that an admin would have to hand over each subzone manually, requiring a macro or a lot of patience. Most likely the same problem is present in the command that lets a player give their residence away. The commands are these:
- /resadmin removeall [player]
- /resadmin server [residence]
- /resadmin setowner [residence] [player]
- /res give [residence] [player]
The default subzone depth is 3, meaning one can have X.Y.Z.W as subzone construction. Aside from obvious inheritage advantages (a castle lord that has access to all houses in the castle, while a landlord owns a few buildings himself), it also has organizational uses. For example, say you do not want all the houses in your city to be in 1 big cluttered list. Instead, you make a subzone for each separate street, remove enter/leave messages, then make subzones for the houses. These now are Residencename.Streetname.Housenumber, and if someone does "/res sublist" inside a street they’ll see the first six houses of the street. If your city has dozens of houses, being able to look through them 1 street at a time is much easier, plus it helps people see what houses are close to each other: The ones in the same street-subzone of course!
As mentioned before, you really want to avoid giving people rights in the main residence. This because they can then spread havoc in your subzones. Instead, you’ll want to take the place where you want help and make it a temporary subzone. Give them rights there, then when the job is done you remove the subzone. This lets you hire workers without constant supervising them. Don’t forget, being a city owner is a great responsibility.
Due to a visual bug in the Residence plugin, removing subzones can be extremely confusing and stressing. The problem is that if you type "/res remove X.Y", it will ask you if you’re sure you want to remove X. It knows you meant X.Y, if you confirm it actually removes X.Y even though it says it removed X, but it’s still really stressing.
If you dislike certain building blocks, you can block them from being placed in a residence. On the other side of the spectrum, you can remove the residence protection on specific object-types, such as torches or sand. This is done with the blacklist and ignorelist. Using a command once will set the item on the relevant list, using it again will take it off the list. Unfortunately these lists are not inherited by subzones, so if someone buys/sells a subzone they can still easily bypass them. Only when you give people rights but keep full control, will such a list be useful. An example would be to blacklist obsidian and bricks in a construction zone, or disallow people to use sandstone in their houses.
|/res lset <ResidenceName> [blacklist/ignorelist] [material]||Adds/removes a material from the residence's blacklist/ignorelist.|
|/res lset <ResidenceName> info||List the Residence's blacklist and ignorelist.|
Since all commands are spread around through this guide, this section groups them together, including a few that weren't named before. This section doesn't include descriptions though. Shortstop notations, that depend on you standing in the right location, are not all included. Those that are have been marked italic.
- /res select size
- /res selext expand [amount]
- /res select vert
- /res create [newresidence]
- /res area add [residence] [newarea]
- /res subzone [residence] [newsubzone]
- /res subzone [newsubzone]
- /res remove [residence]
- /res remove
- /res area remove [residence] [area]
- /res rename [residence] [newname]
- /res renamearea [residence] [area] [newname]
- /res limits
- /res info [residence]
- /res info
- /res area list [residence] #
- /res area listall [residence] #
- /res sublist [residence] #
- /res list [player]
- /res list
- /res set [residence] [flag] [true/false/remove]
- /res gset [residence] [group] [flag] [true/false/remove]
- /res pset [residence] [person] [flag] [true/false/remove]
- /res set [flag] [true/false/remove]
- /res gset [group] [flag] [true/false/remove]
- /res pset [person] [flag] [true/false/remove]
- /res lset [residence] blacklist [material]
- /res lset [residence] ignorelist [material]
- /res lset [residence] info
- /res message [residence] enter [message]
- /res message [residence] leave [message]
- /res message [residence] remove enter
- /res message [residence] remove leave
- /res message enter [message]
- /res message leave [message]
- /res message remove enter
- /res message remove leave
- /res market list
- /res market sell [residence] [amount]
- /res market rentable [residence] [cost] [days] <repeat:t/f>
- /res market buy [residence]
- /res market rent [residence] <repeat:t/f>
- /res market unsell [residence]
- /res market release [residence]
- /res market info [residence]
- /res market info
- /res tp [residence]
- /res tpset
- /res unstuck
- /resadmin removeall [player]
- /resadmin server [residence]
- /resadmin setowner [residence] [player]
- /res give [residence] [player]