Quarantine

Survive the zombie horde! - Version 0.7.1

Quarantine lets you create special zones where mobs spawn and roam around, which players can then join to try to fight for their survival. To improve their odds, they can buy items or sell them. Quarantine has a localized economy, where players get money from killing mobs or selling items. It also has support for leader boards backed by a Redis or MySQL database. You can lock buttons with keys (which players can buy). Also, the player's last health, inventory and locations are saved, so they can resume gameplay at any time. When exiting a zone, pre-game health is restored. This is a hard core survival game, if you die, all your data is deleted, and you loose all your score. Score is obtained by killing mobs, and can be set for each mob type.

Requires WorldGuard, Regios or Residence to work.

Features

Multi zone
Sub zone based mob handling
Local economy with buy and sell signs
Support for enchantments
Leader boards for each zone, backed by a database (Redis or MySQL)
Lockable buttons, with purchasable keys (one time use or not, you decide)
Random mob spawning based on defined regions (all region handling is done by a region management plugin)
Convert money between the integrated economy and an external economy plugin
SpoutPlugin GUIs
Edit in-game messages
Easy setup

Instructions and usage

First, download the file, and follow the readme instructions. As for setting the config, don't put any zones to load on startup, we sill haven't set the regions, you can still name the regions in the config even if we have yet to define them. MAKE SURE the world names for all the zones are valid, that they correspond to the name of a world on your server (the name is the same as the world folders), or you might get errors on startup. If you need help with the settings, the config with notes between "#" is bellow.

Now build something awesome to play in: an abandoned city, a forgotten island, a demolished prison, etc. Don't make it too big, else it might be a bit hard to manage. Only requirement: must be COMPLETELY walled off, players MUST NOT be able to walk away.

For region setup, see the appropriate section.

Now that's done, reboot, or use /qload (zone name) to load up the zone. If anything goes wrong, it will popup in the console.

Finally, we'll set an entrance. Make this a closed and secure spot so players have time to set up their stuff. Use /qsetentrance (zone name) to set it. Now, for the lobby. Don't put it in the zone, but next to it. Make it an enclosed space. This is a little pre-game lobby where you can put signs and stuff for rules or story lines, etc. I just use it to load data :P. To set it do /qsetlobby (zone name). To exit the lobby, players must have access to a teleportation command, either /spawn, /warp or /home.

And, we're done! Test your zone, and then you can add stuff like keys and economy signs. See the section bellow for that (and the leader board setup).

Region setup

These are the currently supported region plugins:

WorldGuard
Regios
Residence

(if you use WorldGuard, get the WorldEdit CUI client mod, so much easier!)
If you don't know how to use either of these plugin, start by reading their wikis. Choose which ever you prefer.
First, we'll start with the main zone, it encases the whole playable area, make sure that you are always within that region when in the zone, else you'll have problems. Name it as you wish, I suggest to use what you set in the config, unless you want to edit it again. MAKE SURE you use the same capitalization! If you get an issue where a player enters, and gets told his last location was invalid, and got reset to the entrance, well, you failed, the main region does not cover the whole playable area.

Ok, now on to the spawning regions. Here, they're called subzones. It's in these that the mobs will spawn. They can cover multiple floors, just make sure again that they're not too big, and not too numerous, I suggest keeping those under 200 blocks in volume (ex.: 10x10x2). Also, MAKE SURE you leave one block space between the region and the walls that may surround it. This is to prevent a spawning problem where mobs get pushed in and up over walls. When it comes to naming them, stick to what you set in the config, and again, USE THE SAME capitalization. For Regios and WorldGuard, these are normal regions, but for Residence, they're subzones of the residence defined for the zone (you have to use the '/res subzone' command to create them).

Buy and sell signs

You right click those to sell or buy stuff, really straight forward. Formats:

Buy an item:

[Quarantine]
Buy Item
(ID)-(amount)-(cost)
(whatever you want here, not used)

Buy a random item:
This takes two signs, first one:

[Quarantine]
Buy Random Item
(amount)-(cost)
(whatever you want here, not used)

Second one, directly adjacent to it:

(ID)-(ID)-(ID)
(ID)-(ID)-(ID)
(ID)-(ID)-(ID)
(ID)-(ID)-(ID)

This is just a example,
You can place as many IDs as you want (or as will fit), separated, on a line, by "-".

Note: for damage values (potion effects, etc.), replace "(ID)" with "(ID):(DamageValue)".

Sell an item:

[Quarantine]
Sell Item
(ID)-(amount)-(cost)
(whatever you want here, not used)

Sell an enchantment:

[Quarantine]
Enchantment
(ID)-(level)-(cost)
(whatever you want here, not used)

Note: make sure you use valid IDs and quantities! For IDs, check the Minecraft wiki, for quantities, it's between 1 and 64. You'll find the enchantment IDs here: http://www.minecraftwiki.net/wiki/Enchantments (they're called EIDs).

Buy a kit:

[Quarantine]
Buy Kit
(kit name)
(price)

Get a kit (lobby only!):

[Quarantine]
Get Kit
(kit name)
(whatever you want here, not used)

Keys and lock signs

You buy keys like items, here's the format:

[Quarantine]
Buy Key
(key name, also it's ID)
(cost)

Keys aren't items though, they're not physical. The ID doesn't need to be a number, it can be a word or more, like "cake key"

To lock a button, place a sign like so next to the button (bellow, above, to the left or to the right). You may only lock buttons (why? because they're momentary, so players can't leave them on).

[Quarantine]
Key Lock
(key name, also it's ID)
(whatever you want here, not used)

Kits

You can rename, add and remove kits. Just modify the entries, following the format from the default config.

The kit format goes like this:

The line is divided in sections by '|'.
If there's no divider, there's only one section.
The first section is the item ID and the amount, separated with a '-'.
If you want to add a damage value to the item, add it the ID, separating them with a ':'
Example: the last item of the donator kit is five colored wool.
The remaning sections are enchantments.
They follow this format: the enchantment ID and the level of the enchantment, separated by a '-'.

Enchantement ID list: http://www.minecraftwiki.net/wiki/Enchantments

Kits are permission controlled. The nodes vary depending on the name of the zone and kit.
Use this format:

quarantine.kit.(zone name).(kit name)

Economy converter

The economy converter allows players to move money between their zone account and an account for an external economy plugin, with fix rates. Take a look at the config, it's pretty simple. There's one special thing though, the permission nodes vary according to the zone you want to let them convert money from (since there's one account per zone).

quarantine.convertmoney.(zone name).(exttoint)
quarantine.convertmoney.(zone name).(inttoext)

ExtToInt means external to internal (economy plugin to Quarantine)
IntToExt means internal to external (Quarantine to economy plugin)

Leader boards

Redis database server software: http://redis.io/
MySQL database server software: http://www.mysql.com/

You'll need to run either of those databases, the choice is up to you. I'll have to assume here you have basic knowledge of how they work, and that you took time to learn a bit about them. All you need to do to get the leaderboards working is to set the correct access information in the config. If you took the time to learn a bit about the software, it'll be simple. Then specify the DB type in the config, which is either 'mysql' or 'redis', and set the 'enabled' field to 'true'. Boot up the you Minecraft server, and any problems should be logged to the console.

Note: to set a score for a mob type, you'll find under the money_rewards setting, last number.

Commands and permissions

Important: a zone is not a sub zone. These commands won't work with sub zone names, only for zones. You do not need to do anything with sub zones once they're defined and set in the config, the plugin will take care of the rest itself.
Note: commands with "*" after the description can only be used in pre-game lobby or in game (zone).

/qload (zone name) : Load an unloaded zone. Permission: quarantine.admin

/qunload (zone name) : Unload a desired zone (flush all players, save the locations, stop the mob check task and disconnect from the leaderboard database). Permission: quarantine.admin

/qconvertinv (zone name) : Convert the player inventories to the new format. This command will be removed in v0.6 Permission: quarantine.admin

/qzones : Display the current zones. Permission: quarantine.play

/qrespawnmobs (zone name) : Respawn all the mobs for a zone. Permission: quarantine.admin

/qjoin (zone name) : Join the desired zone's lobby. Permission: quarantine.play

/qenter : Enter the zone, when in pre-game lobby*. Permission: quarantine.play

/qplayers (optional: zone name) : Display the current player list. Permission: quarantine.play

/qleave : Leave the zone*. Permission: quarantine.play

/qmoney : Tells the player his current money*. Permission: quarantine.play

/qkeys : Tells the player all of his keys*. Permission: quarantine.play

/qscore : Tells the player his score*. Permission: quarantine.play

/qrank : Shows the player his current rank and score for the zone he's in*. Permission: quarantine.play

/qtop (optional page number) : Shows the player the current top five players and there scores for the zone he's in*. Permission: quarantine.play

/qsetlobby (zone name) : Set the lobby for the desire zone. Permission: quarantine.setup

/qsetentrance (zone name) : Set the entrance for the desire zone. Permission: quarantine.setup

/qkits : Show the kits for the zone*. Permission: quarantine.play

/qkit (kit name) : Get a kit, only if you don't have an inventory file*. Permission: quarantine.play

There's an additional "special" permission for the '/qkit' command:
quarantine.kit.(zone name).(kit name).
See the "Kits" section for more info.

/qconvertmoney ('IntToExt' or 'ExtToInt') (amount) : Convert money. See the "Money converter" section*. Permission: quarantine.play

There are additional "special" permissions for the '/qconvertmoney' command:

quarantine.convertmoney.(zone name).(exttoint)
quarantine.convertmoney.(zone name).(inttoext)

See the "Money converter" section for more info.

Config

IMPORTANT: names for the world and regions are case sensitive! So "zone1", "world" and "subzone1", "subzone2" and "subzone3" in this config cannot have different cases from what you've set, else loading will fail. (Of course, case depends on your setup).

Load_on_start:  #Zones to load on startup#
  - 'zone1'
Leaderboards:   #See the leaderboards section# 
  enabled: false
  type: mysql
  redis_db_info:
    host: 'localhost'
    port: 6379
  mysql_db_info:
    host: 'localhost'
    name: 'minecraft'
    port: 3306
    user: 'user'
    password: 'password'
Region_Provider_Plugin: WorldGuard   #Can also be Regios or Residence#
External_Economy_Link:
  enabled: false
  external_to_internal:
    allow: true
    rate: 1  #internal = external * rate#
  internal_to_external:
    allow: false
    rate: 0.5   #external = internal * rate#
Zones:  #The zones, here there's one entry: zone1#
  zone1:  #Name of the zone, also the name of the WorldGuard region for it#
    max_number_of_players: 10
    world: 'world'  #Name of the world the zone can be found in#
    mob_check_task_interval: 300  #Mob check task interval, in seconds#
    soft_mob_respawn: false  #Use the mob check task to respawn a mob instead of it's death?#
    clear_drops: true   #Should mobs drops be cleared?#
    clear_mob_xp: false #Should mobs drop xp?#
    keep_xp_on_respawn: true #Don't loose xp on death#
    one_time_use_keys: false  #Should keys be one time use?#
    keep_money_on_death: false #Keep money after loosing, for next game#
    entrance:  #All values at zero mean an unset location#
      x: 0  #You can set these in-game with commands#
      y: 0
      z: 0
      yaw: 0
      pitch: 0
    lobby:  #Same for the lobby#
      x: 0
      y: 0
      z: 0
      yaw: 0
      pitch: 0
    starting_money: 35  #Money that should be given to players when the first join#
    kits:   #See the "Kits" section for these#
      player:
        - '298-1'
        - '299-1'
        - '300-1'
        - '301-1'
        - '272-1'
        - '297-3'
      donator:
        - '306-1'
        - '307-1'
        - '308-1'
        - '309-1'
        - '267-1|16-2'
        - '364-3'
        - '35:4-5'
      admin:
        - '310-1'
        - '311-1'
        - '312-1'
        - '313-1'
        - '276-1|17-5|16-5'
        - '322-3'
    money_rewards:  #Important: make sure you capitalize the first letter for all mobs names!!!#
      - 'Zombie:10-15-5'  #Reward format : (name of mob):(min money)-(max money)-(score)#
      - 'Skeleton:15-20-6'
      - 'Spider:15-18-6'
    sub_zones:  #List of sub zone, here, three entries#
      subzone1:  #Entry number one, the name is also the name of the WorldGuard region associated to it#
        number_of_mobs: 10
        mob_types:  #Again, capitalize the first letter of the mob names here#
          - 'Zombie'  #In this sub zone, all these mobs can spawn#
          - 'Spider'
          - 'Skeleton'
      subzone2:
        number_of_mobs: 10  #Number of mobs for a sub zone#
        mob_types:
          - 'Zombie'
          - 'Spider'
      subzone3:
        number_of_mobs: 10
        mob_types:
          - 'Zombie'
          - 'Skeleton'

Permissions config

This config can be found in the Quarantine folder, it's called perms_config, and is generated on plugin startup. For most applications, you may not need to change it, but if you do not use any permission plugin, you will need to edit it.

PermissionsSystem: SuperPerms  #This config is case sensitive!!#
PlayerPerms:
- quarantine.play

"PermissionsSystem" is the permission checking system to use. If you use any up-to-date permissions plugin that support SuperPerms, leave the config as is.

If you do not use a permissions plugin, set the field to "PlayerAndOP". This will set all permissions at OP only, unless you add them to the "PlayerPerms" field. This basically creates a simple group system: players, the default group with no permissions, except the ones added to the "PlayerPerms" field, and OPs, who have all permissions.

Messages config

You can edit this config to change the in-game messages and the header used by the zone and lobby signs.

For colors or formats, use the color or format name, in full caps, separating words with a "_". The color and format names are the standard MC ones. Colors must be precede and follow and "%".

Variables (numbers and text) also have to precede and follow a "%", and follow the format "%var-(number)%. If you remove a variable, it will not be displayed. If you add one, it will be ignored and not replaced, if this entry doesn't have as many variables as in the text. Don't edit or remove entry names. To remove a message, replace it with "".

Features to add

(Features marked with "done" will be available in the next version.)

Source

The source code can be found here: https://github.com/DDoS/Quarantine
Feel free to contribute!

Donate

If you want to make a donation for all my hard work, here's a link: Donate here!

Changelog

Version 0.7.1

Lobby signs
Messages config
XP and money configuration options
Fixed the mob check task
Improved the soft respawn mechanics
Better leaderboard GUI

Version 0.7

Added a money converter
Fix an exploit by preventing zone players and regular players from exchanging items
Fix and error when trying to load incomplete zones (not all regions defined) with WorldGuard as a region provider

Version 0.6

Kit selection
XP is preserved after death
Support for Regios and Residence
Optional zone name argument of the '/qplayers' command
The mob check task stops when there's no players
Mob death by pet and fire damage is now properly attributed
Fixed the flame enchantments not lighting mobs on fire
Made the money received announcement less spammy

Version 0.5.1

Compatibility update

Version 0.5

MySQL leaderboards
Spout GUI for the /qtop command
Random item signs
Damage values for IDs everywhere.

Version 0.4.1

Bug fix, see the file description.

Version 0.4

Added support for food levels
Database process on a separate thread
Added the /qzones command
Added the /qplayers command
Added the /qscore command
Fixed a bug when a player leaving the lobby by quitting wouldn't have his inventory reset
Added soft mob respawning
Added damage values to buy signs
Support for the latest RB API
Spout GUI for the /qplayers and /qzones commands
Other code improvements

Version 0.3

Chunk will not unload if they're part of a zone that's in use.
Added support for enchantments (selling and saving)
More flexible and versatile permission system
Entrances can now only be set in the main zone.
Players with their last locations being outside of the main zone will be reset to the entrance. This fixes a bug.
Bug fixes
Code improvements.

Version 0.2.2

Small bug fix, see the file description.

Version 0.2.1

Small bug fix, see the file description.

Version 0.2

Full rewrote
keys
multi zone
sub zone control of mobs
Sell signs
Not just zombies anymore
Score and leader boards
And a bunch more stuff!

Version 0.1

Initial release