Settlers Title
You and your teammates must place your starting settlements and roads wisely, then gather resources to create more, until one team gathers 10 victory points. Based on the popular boardgame Settlers of Catan.

Comments and suggestions welcome :)


See two new video tutorials that came with v1.0 on the Crafting and Resources page and the Development Cards page!


This video previews development up to v0.1. I shamelessly used some familiar music in an attempt to make it more epic...


This video shows gameplay of v0.6 in a 1v1v1 run-through of an actual game.


One giant plugin manages everything. EDIT: it manages MANY things; You would need something else to manage your permissions, for example. Ideally there wouldn't be any plugins installed that interfere with it, and the server would be dedicated to this one game, as opposed to it just being a mini-game on the side.

A template world is needed to build random maps/gameboards from. At the moment my template world consists of the equivalent of the "water tiles" surrounding a catan board, 4 appropriately coloured shipwrecks that act as spawn points, and ten ports. Hexagon tiles are 100 blocks at their widest, but can be generated at any size; you'd want the template to match. My template world is included with the plugin, but if you're adventurous you can modify it or make your own.

Also note that some features are unimplemented; I'm trying to work-in everything I've thought of, but I'm also still open to suggestions for how to implement some Catan features.

The Game

I'd first suggest looking up the rules of Catan if you're not familiar with them.

There are a lot of individual rules that you don't really have to know in order to play, but knowing about Catan will certainly give players an edge. Basically, there are four teams that spawn at different corners of a giant island with 19 different hexagonal regions. The first team to get 10 victory points wins the game. Victory points are primarily obtained by building settlements and cities, but can also be obtained with development cards or by having the longest road. Once your initial settlements are placed, you can find tools in each settlement's chest that are specific to the resource type of the tiles adjacent to that settlement. You must harvest resources and refine them to craft more settlements, roads, cities, and development cards. You must expand from your own roads, and there are specific rules about where you can place settlements; they cannot be placed directly beside other settlements. This means that when a settlement is built, several available spaces on the board disappear immediately; initial placement of settlements is VERY important, just like in Catan.

In addition to manually harvesting and refining resources, the dice will roll every so often (configurable) giving settlements situated on tiles matching the dice roll extra (already refined) resources corresponding to the resource type of the adjacent tiles. These resources appear in the chests inside settlements; only team members can enter settlements to access the resources and tools inside. The 'numbers' of the tiles are made of snow on the ground and are big enough so you can see them on your map, and the dice rolls are true to the probabilities of rolling two six-sided dice. So the best places to put your settlements are on numbers that get rolled most often (6 and 8, then 9 and 5, etc). The numbers used to exist in the sky up to v1.0; unfortunately rendering giant numbers in the sky caused a lot of server lag, so I put them on the ground. The option to turn off tile numbers still exists in the configs. Turning off tile numbers makes it harder to figure out what your numbers are, but it also changes the dice rolls to have EQUAL odds for each number between 2 and 12.

Additional mechanics include development cards, which work pretty much the same as in Catan (see development cards), and PvP.

Similarities to Catan

  • Randomly generated world consisting of 19 hexagons.
  • Randomly generated and distributed numbers for each hexagon.
  • 4 teams: blue, red, brown, and white.
  • Hand-held maps that display the numbers, player settlements and roads, and hexagon layout. Exploration is required.
  • Resource costs of settlements and roads are the same.
  • Resource costs of cities is the same; you can upgrade settlements to cities.
  • You can place settlement and road "blocks" only in the appropriate places on the map; settlements go on diamond blocks, roads on emerald.
  • You can place city "blocks" on workbenches in settlements to upgrade them to cities.
  • Scoring is the same.
  • Random 'dice rolls' every [configurable time interval] also gives refined resources.
  • Resource costs of development cards is the same.
  • Converting refined resources 4:1 by crafting resource rupees.
  • Converting 2:1 or 3:1 with controlled ports.

Differences and Minecraft-Related

  • This game is obviously first-person, from the perspective of a single settler.
  • The team size is open-ended right now; you could have 10 players on each team for 40 players total, or you could have single-player teams.
  • There are no "turns" to speak of. It's a big free-for-all for getting to the good spots first.
  • Players can collect resources from the tiles themselves, with the right tools.
  • Wood and iron tools spawn in chests in settlements and cities (respectively) adjacent to the appropriate tile. For example an axe for forest.
  • You have a chance to find stone tools, when you successfully harvest a resource.
  • Manually collected resources must be 'refined' to make collection go a bit slower.
  • PvP can be enabled (or not).
  • Dying for any reason makes you drop half of your unrefined resources (this will eventually be configurable).
  • Items do not stack.
  • The "resource type" for the desert is weapons. They will spawn in adjacent settlements like other tools.
  • Mobs will spawn in the tile blocked by the robber.
  • Rolling 7 causes resources stored in all chests to be reduced by half (unimplemented)
  • You can move faster on your own roads (unimplemented)
  • You move slower the more resources you are carrying (unimplemented)
  • There will eventually need to be a trade interface of some kind (unimplemented)

Resources and Crafting Recipes

These are nothing like vanilla Minecraft. Read all about them on the Crafting and Resources page.

Development Cards

These work almost the same as in Catan. Read all about them on the Development Cards page.


The default amount of points needed to win is 10. This is how Catan works, but this number is configurable if you want to try a different number. Notes: settlements and cities only count when placed (not when crafted), cities REPLACE settlements on the board (so you get 2 points for the city, but you lose 1 from the settlement it replaced), victory point cards can be held onto indefinitely and also only count when placed.

  • Settlement built: 1 point
  • City built: 2 points
  • Victory point development card: 1 point
  • Longest road: 2 points
  • Largest army: 2 points

Largest Army

Every time your team places a knight, it is recorded. The team that places the most knights controls the largest army and is awarded 2 temporary victory points. If another team is able to play MORE knights (they must beat your number by at least 1) the 2 points go to them instead.

Longest Road

The team with the longest unbroken stretch of road of minimum length 5 gets 2 temporary victory points. If another team builds a LONGER road (they must beat your road by at least 1) the 2 points go to them instead.

Known Caveats

  • Because block metadata is not permanently stored, no new settlements, roads, or cities can be placed ever again on a map if the server restarts (the diamond blocks, emerald blocks, and workbenches contain metadata that links them all to the "virtual board"). I'm not sure how to remedy this problem; at the moment I just hope that the server doesn't restart while a game is in progress.

  • Lag. Lag occurs quite predictably in a few cases- worst of all when a new map is being generated, and also when someone places a settlement or (particularly) a road. EDIT: I have scheduled world generation, tile number generation, and road placement to reduce a lot of the lag, however it seems that any blocks generated in the sky are lag-intensive. Overall lag has improved, but you may still see some, especially during world generation.
  • Stuff in the sky. As stated above, the blocks in the sky seem to be lag intensive. I think this has to do with lighting, specifically lighting all the blocks below one that you change in the sky. In Minecraft 1.6.4, colored wool doesn't show up on maps, so in order to make maps work for this game, I put blocks in the sky to mimic roads and settlements that render the appropriate colors on maps (ice for blue, TNT for red, etc). Newer versions of Minecraft do seem to render colored wool on maps, so I anticipate that when I move to the next recommended Bukkit build, there won't be such a need for blocks in the sky, and lag will improve. If it becomes dire enough, I suppose I could remove them now and make maps much less useful, but I'd first like to see how actual decent servers handle this plugin (my machine struggles but it's not the most powerful).

  • Upgrading a settlement to a city requires you to place a block on top of a workbench. This can be done by shift+right clicking instead of just normally right clicking to place the block (otherwise it just opens the workbench inventory). I didn't think that through and I'll try to come up with a better solution. Cities themselves are boring at the moment too (just stone settlements) so they will likely look better at some point.

  • The template world is copied by a non-bukkit Java FileIO method during world generation. I'm not sure if this will raise red flags; it doesn't for me.

Target Features for Next Release

  • COMPLETED; v1.2 awaiting approval:
    • A consequence when a 7 is rolled; remove a configurable amount of refined resources from chests in settlements and player inventories.
    • Increased movement speed on your own roads.
    • Different levels of shears, to make it more consistent with wood -> stone -> iron levels of other tools.
    • Lag reducing features, specifically around the knight and it's movement and dice rolls.
  • IN DEVELOPMENT; likely for a future release:
    • Allowing 'monopoly' to also rob chests in settlements, not just player inventories.
    • Different configurable run speeds on roads to be used as perks.
    • Stone-tool drop chance to be implemented as a perk.
    • On victory, return a list of victorious players for other plugins to capture.
    • Each unrefined resource you carry slows you down a little bit.
    • Adding helmets, boots, and novelty weapons/items as rare drops or perks.
    • Trade interface.


The same as any other Bukkit plugin except that you need to use the template world that I've packaged with the jar file, and you need to have a lobby world called "settlers_lobby". Note that you can modify these worlds to your liking (by default only ops can), but for now you have to keep the names the same. See below for more info about how these worlds work, if you really want to mess with them.

  • Put settlers.jar into your plugins folder.
  • Put settlers_template folder into the directory that contains your worlds.
  • Ensure that you have a world called "settlers_lobby" in your worlds folder.
  • Configure your server properties file; see below.
  • Remove (or move) your old Settlers config file if you have a previous version installed, or the new configs won't generate.
  • Run the server to generate the default configs.

Lobby World

This is where your players will come when they join, and where they will join the queue for the next Settlers game. In the very first version of Settlers I packaged my own settlers_lobby world with the plugin (which you could still use, but you don't have to). This used to be where teams were manually created, but now team generation is done automatically when there is a full queue. This means that your lobby world can be anything you want, but as stated above, the name of this world must stay as "settlers_lobby".

Template World

This world is copied to form the base of each new board you generate. Think of this as the outer pieces of the Catan board that connect together to make the shoreline. If you want to make your hexagons bigger or smaller, you have to change this world to match. Actually, if you make the hexagons smaller, there will just be more sand between the shoreline and the hexagons; the overall board will stay the same size. If you make the hexagons bigger, the shipwrecks that act as spawn points and the ports will all be overwritten during world generation. Also, the spawn point locations themselves are in the configs, so if you change the size of the board, you can go in to the configs and change the spawn point locations for the teams. As stated above, the name of this world must stay as "settlers_template".

Server Properties File

While some of the properties in this file are up to you, and they don't all apply once worlds have been generated, these are some things to configure to be safe:

  • level-name=settlers_lobby
  • level-type=FLAT
  • spawn-npcs=false
  • spawn-animals=false
  • difficulty=0
  • gamemode=0
  • spawn-monsters=false
  • generate-structures=false


At the moment not everything I'd like to be configurable is; this will be extended to include as many features as possible. The config file itself is fairly self-explanatory, but below is a list of configurable features (not the actual names of the variables in the configs).

  • Points required to win a game. Defaults to 10.
  • Size of generated hexagons. Don't change this unless you are going to also modify the template world.
  • Toggle for generating tile numbers. If on, the dice roll is two 6-sided dice, and each tile's number has the correct probability of being rolled. If off, the dice roll is one 12-sided die, and all tiles have the same chance of being rolled (because you can't really tell what the numbers are).
  • Height of numbers in the sky; this doesn't apply to tile numbers as of v1.0 but the road and settlement markers in the sky also use this value. Try lowering it to decrease lag.
  • A list of breakable blocks when in-game. You don't want things like refined resources (wood, wool, etc) to be breakable, because settlements and ships are made out of that stuff.
  • Difficulties for harvesting unrefined resources. Try this out in game before you mess with these numbers; they can be touchy.
  • The amount of raw resources required to make one refined resource. Right now it's shared for all resource types.
  • Players needed in queue to automatically start a game.
  • Maximum worlds to run at once.
  • Frequency of dice rolls.
  • Countdown time from full queue to game start. This will need to be higher if sky numbers are on.
  • Location of spawn points, in case you modify the template world.
  • Chance of dropping a random stone tool when successfully harvesting any of the 5 unrefined resources.


In hindsight, the use of the prefix "set." seems confusing... Sorry!

  • set.givemap:
    • description: Give yourself or another player an appropriately scaled map of the world they're in.
    • usage: set.givemap [other_player]
  • set.tolobby:
    • description: Ports yourself or the given player to the settlers_lobby world.
    • usage: set.tolobby [other_player]
  • set.toworld:
    • description: Ports the given player to their team's spawn in the given world.
    • usage: set.toworld player world
  • set.toteam: (DISABLED; needs to be updated)
    • description: Adds the given player to the specified team.
    • usage: set.toteam player team
  • set.start:
    • description: Forces a new game to start with the current queue, which is then cleared.
    • usage: set.start
  • set.enqueue or set.q:
    • description: Adds player to the queue for the next game. Works on self if no player specified.
    • usage: set.enqueue [other_player]
  • set.dequeue or set.dq:
    • description: Removes player from the queue for the next game. Works on self if no player specified.
    • usage: set.dequeue [other_player]
  • set.all:
    • description: Sends a message to all players in the current world.
    • usage: set.all message
    • description: Sends a message to all players on your team in the current world.
    • usage: message


Like the configs, these need to be extended. Right now only access to commands and some block manipulation in the lobby and template worlds have permissions. As stated earlier, you will need another plugin to actually manage permissions.

  • settlers.*:
    • description: Gives access to all non-admin settlers permissions.
    • children:
      • settlers.givemap_self: true
      • settlers.queue_self: true
  • settlers.givemap_self:
    • description: Use of set.givemap command for self.
    • default: true
  • settlers.queue_self:
    • description: Use of queuing and dequeing commands for self.
    • default: true
  • settlers.admin_commands:
    • description: Use of all admin settlers commands.
    • default: op
  • settlers.block_manipulation:
    • description: Allows block breaking in the lobby and template maps.
    • default: op

To Start and Play

When players join your server, they should come to the lobby world. From there, they can use the set.q command to queue for the next Settlers game. Alternatively, ops can use the set.q [other_player] command to queue people. The intention is that a command block (or something like it) could be setup so that players don't need to type the queue command themselves.

Once the queue is full, a new game automatically starts.

Game End and Victory

When a team gets the required amount of points for victory, the game ends and all players are sent back to the lobby. As stated in the caveats section, the instance of the game is neatly cleaned up when a game ends due to victory. If the game is abandoned, the data structures in memory are cleaned up but the world itself will linger and need to be manually deleted.

I want to find away to return a list of victorious players in a form that can be captured relatively easily by other plugins, which may facilitate individual scores for unlocking perks, for example. Any suggestions on how to approach this would be appreciated.


Posts Quoted:
Clear All Quotes

About This Project

  • Project ID
  • Created
    Mar 31, 2014
  • Last Released File
  • Total Downloads
  • License



Recent Files