What is a Village?

A NPC village is a set of one or more houses. For this tutorial, the following properties of villages are important:

• Village Center: The center is at the average coordinate of all houses.
• Village Radius: The (euclidean) distance from the village center to the house farthest away from it. It is at least 32 blocks, however.
• Village Boundaries: Now that we have a center and a radius this should be obvious. Imagine a sphere around the village center.

You can see these values (and others) ingame by using Village Info (Mod). I highly recommend using it if you’re trying out new design, or if you just want to understand what’s going on with your village.

About Houses

What is a House?

In Minecraft, a house is a wooden door which meets a certain condition: there must be a clear inside and outside. To determine the inside and outside, Minecraft compares the 5 blocks behind the door to the 5 blocks in front of it (all inline with the door). If there are more roofs or roofed blocks on one side, this side will be the inside. If both sides have the same amount of roofs or roofed blocks, the door won’t be considered a house at all.

A block can be a roof if the block itself is not fully transparent. A roofed block has a non-transparent block anywhere above it (along the Y-axis). Non-transparent blocks are blocks which diminish sunlight when it passes through or completely stop it. For example, opaque blocks (like stone and dirt) completely prevent light from passing through, while water reduces the light level by 3. Stairs and single slabs prevent light propagation as well. So these blocks can be used to create a roof.

Apparently, the direction the door is facing also plays a role here. Whenever you place a door, you’re looking at the front of it, i.e., the direction you’re facing is the one that matters. Blocks on the other sides, and blocks farther away than 5 blocks have no impact at all. Only the 10 blocks inline with the door (and everything above them) matter.

Here are some examples:

Note that there are no roof blocks above (off-screen). I put the torches there to make counting easier for you. They have no impact because they are not inline with the door.

As you know, doors consist of two blocks vertically. Both blocks are checked individually. If either level passes the house check, the door is considered a house.

Adding Houses To Villages

Every few seconds, Minecraft scans the area around villagers for houses. The area it scans is a cuboid with width and length = 33 blocks and height = 9 blocks, the villager being in the center. This means that in order to add a house, a villager needs to be within 16 blocks of the door in both horizontal axes (x and z), and within 4 blocks vertically (y).

Houses are always scanned from bottom to top, so if the lower and upper level checks would lead to different insides and outsides, the lower level counts. There is one exception though: if the villager is exactly five blocks above the door when the door is scanned for the first time, the lower level won’t be checked at all.

Here’s an example:

On the top level, there are no roofs or roofed blocks on the left side, but one on the right side, so the inside should be on the right. However, on the bottom level, there are two roofs on the left, so in most cases, the inside is on the left.

When a door passes the check, it will be added to an existing village if the distance to the village center is at most 32 + |Village Radius| blocks (in other words, if the door is at most 32 blocks away from the village boundaries). If there is none, a new village will be created for the house. That’s why all houses in the screenshots up until now are technically villages, too.

Refreshing and Removing Houses

Once a house is added to a village, a villager has to stay nearby to “refresh” it (range is the same as for adding houses: up to 16 blocks for both horizontal axes, and up to 4 blocks vertically). Otherwise, the house will be detached from the village after about 1 minute. If there are no other houses in the village, the village will be removed from the game as well.

When refreshing a house, it doesn’t matter if the house check fails. So when trying out house setups, make sure to destroy the door block after every change to force the game to check the door again. Since Minecraft 1.4, village data is stored in the savegame, meaning houses will not be rechecked after a restart. Walking out of range to unload their chunks will still reset them though. There is one exception: villages in the spawn area will not be reset this way because the area will always be loaded.

About Villagers

Home Village

Although villagers wander around randomly, they usually stay within the village boundaries. They are also able to locate villages whose boundaries are up to 32 blocks away, and will try to reach them quickly.

Finding Shelter

During night time or downfall, villagers try to find shelter. Usually, they pick the least occupied house within 16 blocks. If there is none, they pick the closest house. However, many players are observing that villagers are clumping up in one single house. I think this happens because they usually start looking for shelter at about the same time, before any houses are occupied. In this case, they’d pick the house that was first attached to a village (which is random after restart).

After picking a house, they try to reach the position two blocks behind the door (inside the house). They will also move to a different house every now and then, but only if there is an exit that doesn’t involve opening a door (they aren’t able to do so at this point).

Breeding

When two villagers are close to each other, there is a chance that they start mating and give birth to a baby villager. They can only breed if they are inside a village and if the population is below 0.35 * |Amount of Houses| (population limit), i.e., you need roughly three houses per villager.

When villagers are killed by mobs, or by a damage source that isn’t related to entities (e.g. lava, drowning) while a player is nearby, the whole village won’t breed for 3 minutes.

Population Explosion

For breeding, a villager is considered inside the village if he is inside its boundaries. But to count villagers, Minecraft uses a cuboid with width and length = 2 * |Village Radius| and height = 8 blocks. Here’s an illustration of the resulting zones: