Bukkit

Overview

Notice (Statistics Collections)

THIS PLUGIN COLLECTS STATISTICS LIKE YOUR IP, PORT, AND NAME. I USE THIS INFORMATION TO JUST HAVE AN IDEA OF HOW MANY PEOPLE USE IT AND SUCH. TO DISABLE YOU NEED TO SET THE CONFIGURATION OPTION CHECKFORUPDATES TO FALSE IN THE CONFIG FILE.

Notice (Configuration)

THE CONFIGURATION IS CREATED IN THE SERVER ROOT DIRECTORY. THIS IS INCORRECT AND WILL BE FIXED IN FUTURE VERSIONS. IT WILL BE CALLED kserver.config.yml. I MADE THIS IN BIG LETTERS BECAUSE I KNOW SOME OF YOU ARE MISSING IT.

Notice (Dual Factions)

TO RUN ORIGINAL FACTIONS YOU HAVE TO CHANGE THE COMMAND PREFIX FROM /F TO SOMETHING ELSE. FOR EXAMPLE TO CHANGE IT UNZIP THE KFACTIONS JAR FILE THEN EDIT THE PLUGIN.YML CHANGE THE F: TO W: THEN ZIP IT BACK UP AND RENAME IT TO KFACTIONS.JAR. NOW ALL COMMANDS START WITH /W INSTEAD OF /F ALLOWING IT TO RUN ALONGSIDE THE ORIGINAL FACTIONS PLUGIN IF SO DESIRED.

Notice (Equivalent Exchange 2) (EE2)

If you are running a Tekkit server and you find that you have to ban many of the items in EE2 because they bypass the factions then send me an email at kmcg3413 at gmail.com and I will send you a patched version of EE2 that fixes a few dupes and makes EE2 play correctly with plugins. So why run a server with most of EE2 disabled when you do not have too?

Notice Tekkit (Special Players)

All of the machines in Tekkit use a special player to represent the machine when it places, breaks, or interacts with blocks in the world. This is done on purpose to allow plugins to cancel these events. These are the fake players for each modification. The EE2 special player may work below but the last time I used Tekkit this would not work. However, I have not messed with the most recent version. This list was copy and pasted from another player's list.

[computercraft]
[redpower]
[redpower2]
[railcraft]
[equivalentexchange]
[redpower]
[industrialcraft]
[buildcraft]

To allow these to work on your claimed faction land you should add them as a friend to your faction with a rank like: /f addfriend [buildcraft] 900. Which, would give any BuildCraft machine a rank of 900 with your faction which should exceed the default 500 rank for build and place and the default 250 rank for interaction on all chunks. You could use the rank of 500 instead of 900 as long as this rank gives it permission to interact, build, or place on your claims.

Tekkit Or Bukkit

From my testing this package should work as is on both Tekkit and Bukkit based servers. If you find out other please let me know.

Developers

See bottom of this page.

Overview

Provides player based land management (land protection) (or spawn protection), numeric rank based, protection from specific block types per chunk (claim), a power system based on charging, and protection can be for build/place, interaction, or both.

Quick Install Guide

To get up and running with this plugin as fast as possible. First download the plugin then place the JAR file into the plugins directory in your Bukkit server root directory. Now, start your server and this will cause the plugin to create a configuration file in your server root directory. It will be named kfactions.config.yml. Shutdown your server now. Edit the configuration how you like it. Make sure to add the worlds you want it enabled on into the configuration if you use non-default world names and worlds. Also, scroll down or use the menu to go to the Example Configuration (kfactions.config.yml) section so you can understand each configuration parameter.

This plugin at this time uses no permissions.

Detailed Overview

Claim Are Chunk Based

A chunk or also known as a claim is 16x16 in width and length and extends from bedrock to the sky. All chunks are claimed on the boundary of 16 blocks by 16 blocks. You can make zero or more claims per faction.

Numeric Rank Based

The standard factions is limited to a few permissions. This plugin provides permission to do something based on the rank of the player trying to perform an action. For example the plugin can provide build, place, or interaction protection per claim (chunk). Players outside the faction have a rank of -1 when trying to perform an action. Anyone in the faction has a rank of 0 to 1000. When a player joins a faction they are given a default rank of zero. Any member of the faction can assign (or change) the rank of another member if said member is less than their rank, also a members rank can not be set higher or equal to the member whom is setting their rank. For example the owner/creator of a faction has a default rank of 1000 which means he can change the rank of anyone with a rank of 999 or below, but he can not assign anyone a rank of 1000 or above.

Local HTTP Server With Statistics

This feature is going to be ported into the KFaction plugin as it currently resides in another plugin.

Protection For Specific Block Types Per Claim/Chunk

You can set the required rank to break/place specific blocks per claim/chunk or required rank for interaction per chunk. What this means is that you can restrict who can break/place cobblestone, or restrict who can open chests, machines, or such other things. A required rank of 250 for interaction would mean that someone must have a rank of 250 or higher to open any chests on the claim/chunk.

Land Management / Land Protection

You can create dummy factions to protect certain regions of your world. For example you can create a faction and from within that faction claim land for spawn. Then you could set certain special options such as NOPVP, NOBOOM (no explosions), and NODECAY (no power decay). This would restrict players from attacking each other, explosions damaging the land, or the power from decaying over time.

And, with the high customization of permission for specific blocks you could allow players to interact with specific blocks or build and place certain blocks. For example your spawn may have certain blocks for display purposes only which you do not want players using and at the same time you may have other specific blocks that you do want the player to use. As in you might only want players to interact chests and crafting tables and not the furnace.

Charge Based Power

The standard factions plugin basis faction power from how many players are in the faction and how many times they have been killed. This plugin instead basis faction power on charging it. To charge the faction the player holds an item in their hand and types /f docharge then presses enter. If the item is worth anything what it is worth will be added to the faction power and the item (or item stack) will be removed from the player. The value of items are based on an exact copy of the EE2 modification (mod). So if you have EE2 installed on your client the EMC value of an item is the exact amount of power it gives. For those of you on a client without EE2 items will still charge but you will be unable to see the EMC toolt tip that appears when you hover the mouse over an item. Instead you can use /f charge to see how much what you are holding would charge the faction power.

A faction loses charge/power naturally overtime and is increased by claiming more land. Once a faction's power reaches zero other players can destroy the faction land using explosives or claim the land. I will explain more about this in the sections below.

Configuration And Settings

Modify Charge For Item/Block

Once the plugin has properly initialized it will create a file in the root server directory named kfactions.emcvals.txt. If you open this file you will notice one entry per line. The format of the entry is something like <numberA>:<numberB>=<numberC>. The numberA is the type ID of the item or block, and numberB is the value of the data portion. Most of the time the data identifier is going to be zero, but there are cases where it will change depending on the item/block type. The numberC represents the charge value of that item/block. If something is not listen then the charge value is considered zero. The values are exactly duplicated as EMC values from the EE2 (Equivalent Exchange) mod.

NOPVP, NOBOOM, NODECAY

To set a faction with NOPVP, NOBOOM, or NODECAY you will have to use the server console and enter a command like such:

f nopvp <faction-name>

f noboom <faction-name>

f nodecay <faction-name>

The decay is the normal charge/power usage per hour multiplied by the number of land claims for a faction. The NOBOOM stops explosions from damaging the faction power. The NOPVP stops damage when the target is a player. So player can not be hurt but mobs can be.

How To Bypass Protection (Insertion Into Faction)

The plugin does not allow OPs to bypass the land protection mechanisms. I may change this in a future version. So at this time only someone with access to the server console and bypass the land protection mechanisms. Basically, what happened was originally these commands could only be executed on the console, but I changed that because someone wanted users to be able to execute them if they had a permission. Now, if you /op <name> someone they have all permissions therefore now anyone who is OP can also execute these commands. Most server that I know of do not assign OP to players but instead assign permissions for various commands through plugins such as essentials therefore if you do it this way you can limit who can execute these commands.

You need the permission (by default) kfactions.bypass to execute these commands. You can change this permission in the plugin configuration file which is created once the plugin is enabled for the first time if the file does not already exist.

To do this you must insert yourself or the character that needs to bypass into a faction using: f stick <faction-name> <player-name>. This will remove this player from their current faction and place them into the specified faction with a rank of 1000. To pull a character from a faction and place them into no faction use: f yank <faction-name> <player-name>.

World Anchors (Tekkit Or Modded Server/Clients)

I want to allow more then just world anchors to be restricted, but for now this is what you get. There is a hard coded limit of 2 world anchors per faction. In the event that a world anchor is removed but is still registered as being there for the faction you have a command that can be executed from the console to un-register it.

The command is:

• resetwa <faction> <world> <x> <y> <z>

If the command was a success then you will see a message displayed indicating so or a message indicating a failure.

Also, to display world anchors for a faction you must insert yourself into that faction then issue this command:

• /f showanchors

I think at the moment a bug may exists where if an explosion destroys a world anchor it will not become unregistered and someone with server console access will be forced to execute this command to remove the registration of it.

Show Faction Name In Chat

There is tested support for EssentialsChat and Herochat. I will show examples for both of these. Other plugins that modify the chat may also be supported if they provide you with the ability to insert any of the following tags into their format specifier:

• {faction}
• {FACTION}
• [faction]
• [FACTION]

EssentialsChat

Edit the config.yml. Then find this line:

format: '<{DISPLAYNAME}> {MESSAGE}'

Change it to:

format: '{FACTION} <{DISPLAYNAME}> {MESSAGE}'

As you can see the {FACTION} will be converted into the faction name and will prepend the chat message. You can set this for specific groups as support by Essentials.

Herochat

Find the line that specifies the format you wish to include the faction name in, and then edit it to add the {faction} tag.

format:
  default: '{faction} {color}[{nick}] &f{prefix}{sender}{suffix}{color}: {msg}'

Player Overview

There are seven important commands for players using this factions derivation. They are:

• /f create <name>
• /f charge
• /f claim
• /f sethome
• /f home
• /f seechunk
• /f c <message>
• /f rename <new-name>
• /f autoclaim

These commands can create a faction, charge the factions with power, claim a chunk of land, and set the home so that /f home can be used to teleport the player back to the land claim in the event that they die. To check how much something will charge you use /f chkcharge. What you are holding in your hand is used to charge the faction and it will consume entire stacks so only hold exactly what you wish to charge with. The faction must have some charge before you can execute the /f claim command to claim land.

The /f c <message> allows you to communicate with your faction members. It will send a single message that will be broadcast to all factions members. I prefer this way of talking because it is harder to accidentally send a faction message to everyone on the server because you forgot you had all your chat going to global instead of just your faction.

The /f seechunk command is a highly useful tool for those who know of it's existence. It allows you to see exactly where the chunk is that you are standing on by walling the chunk in using glass blocks. These glass blocks only appear client side and are not actually placed on the server. After 10 seconds they will disappear. They only fill in areas with air so if you are underground you might be forced to mine outward a few walls to actually find the borders of the chunk. However is you find one wall there is 16 blocks between the glass walls. If you find a corner you know there is 16 blocks one direction and 16 blocks the other. This is also highly useful when trying to set ranks per chunk for building and interaction either using the commands on a per chunk basis or a block basis per chunk.

The /f autoclaim is useful for some people who wish to simply walk around their base however, it does not ensure that walls are protected. In a future version I may make this possible.

Also:

• /f tptp <player> <destination-player>

This will teleport the first player specified to the destination player specified. It will only work with players in your faction and you must be equal or greater in rank to execute this command. The reason the ranking is enforced is because a higher ranked player may be in a secure vault that normal members do not have access to and the normal member could simply teleport himself to the higher rank player and log out then log back in later and potentially steal from the faction.

The next important commands are:

• /f invite <player-name>
• /f join <faction-name>
• /f setrank <member> <newrank>
• /f kick <member>

These commands allow membership to be controlled and also access permissions on a rough level.

More, important commands allow a finer grain of permission control:

• /f curank <rank> (minimum rank to use things on current land claim)
• /f cbrank <rank> (minimum rank to build on current land claim)
• /f setmrz <rank> (minimum rank to execute zap commands)
• /f setmrtp <rank> (minimum rank to execute teleport commands [including /f home])
• /f setmrc <rank> (minimum rank to claim land)
• /f setmri <rank> (minimum rank to invite people to the faction [using /f invite]

And, finally:

• /f br <rank> (hold block in hand to set minimum rank to place/destroy block)
• /f bru <rank> (hold block in hand to set minimum rank for usage/interaction)
• /f lbr (list build/destroy block ranks for current chunk)
• /f lbru (list interaction/usage block ranks for current chunk)

The key concept to remember is that these operate on a individual chunk. So you need to use /f lbr and /f lbru to make sure you have set the permissions on all the chunks you wish that permissions to be on. Otherwise, you may find that half you protected vault is on a chunk which does not have the block permissions correctly set and thus players are able to break blocks to enter into it.

Another interesting concept is using the block ranks to allow someone to do something they normally would be able to do. For example normally you may use block ranks to prevent someone from doing something they can already do, but you can also allow someone to do something. The way you do this is by setting a low rank for the block rank since this will override say the chunk's build or usage rank thus denying them ability to do anything but exactly what you set with the block ranks.

Faction Power Explanation

Your faction power serves two purposes. The first purpose is it prevents people from standing on your land and typing /f claim and thus stealing your land from you. If you faction power is zero then anyone can steal your land if they stand on it and execute the claim command. The second purpose is that it provides defense from explosions. For each block that starts to break from an explosion a set amount of power is deducted and the block is prevented from breaking. So if you run out of faction power then explosions will start destroying your land. Of course you could build a nice border to your land so that explosions can not reach your base, but then your enemy is going to attempt to use a cannon to launch the explosive charge into your base. You can even build your base out of materials that resist explosions which would keep you from losing any power since they will not break, and in this case your enemy will likely use bigger explosions like from a nuke (if you playing with tekkit).

I need to make a configurable option that would allow obsidian bases to have some kind of a weakness because at this time if your are playing vanilla bukkit then there is no explosion that will destroy an obsidian block and thus this could be used to prevent someone from knocking someones faction power down.

Data On Disk

The plugin saves faction data to the disk every 15 minutes, and also when you properly shutdown the server by giving the stop command. The data is stored in the YAML format which allows you to read and edit the data by hand using any text editor. The file is named kfactions.data.yml.

If you have used a version prior to version 1.1.9 you may find another file named plugin.data.factions which is the old data format and file. This file uses a binary serialization format specific to Java. You can delete this file if you find it and you have not had any problems after upgrading to 1.1.9. But, keep a backup of it if you have not tested the upgrade for long as it holds the original copy of your data. And, if you run into upgrade problems we can fix your data using this old file.

Developers

If you are a developer and you think this plugin is almost perfect, but you have an itch to fix something or change it. Then you will be happy to know that the GIT repository contains the source code, and each JAR (download) contains the Java source files right beside the class files. Just unzip the JAR and you shall find them.

The only thing that I ask is if you change or add a feature that you do it in such a way that it can be toggled on and off either during run-time or only at load-time. I ask this because it will allow people to have the plugin do as they wish and makes it a much better plugin overall.

Also, if you send me your patch I can apply it and include it in the next uploaded build.

Need A Feature?

If you need a feature send me a private message or leave a comment below explaining it. You can also reach me at [email protected].

HeroChat

Support for the latest version of Herochat to be able to use the {faction} tag.

format:
  default: '{faction} {color}[{nick}] &f{prefix}{sender}{suffix}{color}: {msg}'
  announce: '{color}[{nick}] {msg}'
  emote: '{color}[{nick}] * {msg}'
  private-message: '&d{convoaddress} {convopartner}&d: {msg}'

As you can see above the {faction} entry will be replaced with the faction name. You can insert coloring or anything provided by Herochat and it should work file.

FAQ

How Much Power Does Faction XYZ Have?

Type /f who xyz.

What Faction Is Player ABC In?

Type /f who abc.

How Do I See My Personal Power? Or The Faction Power?

A individual player has not power, but rather the faction has the power. To see the faction power type /f who.

Where Is My Configuration!?!??!

I know I made a mistake when writing this plugin. It should technically be generated in /plugins/KFactions/ as config.yml, but instead you will find it in your server root directory named kfactions.config.yml also the data file is kfactions.data.yml.

I Want To Show A Player's Faction Beside Their Name In Chat

See the section in this document Show Faction Name In Chat.

How Do I Use Faction Bypass As It Is My Server

To use bypass is a permission that you must have assigned or will have assigned if your have operator privilege (/op <name>). This privilege allows you to execute the protected commands /f stick <faction> <player> and /f yank <faction> <player>. These will insert the specified player into the specified faction, or remove the specified player from the specified faction.

Therefore, for example if you need to place or destroy blocks or modify faction (bypass) you need to insert yourself into that target faction. You will be inserted with a rank of 1000 which can only be obtained under normal circumstances by the creator of a faction and under normal circumstances can never be assigned to anyone else. So you should have full access to the faction.

Feature/Work Requests

This is a list of things that I do not want to forget about doing. If you are a programmer you can help implement some of these. The source code is contained in the JAR that is downloaded. You will also find a GIT repository on the repository tab for this project at the top of this page. For a more easily viewable format you can also use https:github.com/kmcguire3413/KFactions. Both repository are kept synchronized.

1. implement vault integration (implement faction creation cost option)
2. implement /f map improve /f map display
3. have world edit support for claiming large area (more admin type method)
4. feature that can be toggled on/off which displays when an explosion happens and land is damaged
5. implement support for essentials chat
6. move configuration files from server root into proper sub-folder of the plugins directory
7. add in localization support for all messages including help display
8. actually denote and release the source code under an open source license
9. add web statistics for server startups using basic server information for profiling userbase
10. add update notification to OPs and players with bypass permission (new version notification)

Example Configuration (kfactions.config.yml)

If you start the server with the plugin loaded it will create a default configuration. This is just here to help show you how to actually set values and lists. When I release a new version I will update this section before the release so towards the end you may find configuration parameters that are not populated in your configuration. Just check if there is a pending new version to be released and if so that will be the reason.

noGriefPerWorld:
 - world_protected_example
friendlyFire: false
scannerChance: 0.01
landPowerCostPerHour: 85.0
worldsEnabled:
- world
- world_nether
- world_the_end
enabledScanner: true
scannerWaitTime: 3600
powerUsedToProtectBlock: 7.485380116959064
randomModifierOnProtectBlock: true
powerUsedEachClaim: 0.0
numberOfFreeClaims: 2
bypassPermission: kfactions.bypass
repawnAtFactionHome: false
percentageofPowerOnTeleport: 0.1
requirePermission: false
opRank: -1

• opRank this sets what rank OPs are given relative to any actions, but if they would have normally got a higher rank then it will override the opRank; for example if you have a rank of 900 in your faction and opRank is set to 600 and you are OP then your rank will be 900; if you have an opRank of 900 and normally you would have a rank of -1 then you will have a rank of 900 if you are OP also; this basically makes it easier to perform administrative tasks
• bypassPermission will allow anyone with the permission to execute special administrative commands like /f stick, /f yank, and others this allows you to assign the ability for someone to manage factions but not assign them OP; this is badly named and needs to be updated to something like adminPermission or similar
• repawnAtFactionHome will cause you to respawn at the faction home when you die
• requirePermission will require the permission kfactions.usage for any player to use this factions plugin
• percentageofPowerOnTeleport is the amount of power used for teleport commands; this is only effective is /spawn and other commands are disabled, but to disable it just set this to zero
• powerUsedToProtectBlock is the amount of power used per block that would be exploded by the explosive (TNT, Nuke, ..) and if the faction does not have enough power to pay this then the block will actually be destroyed which is why when your power falls to zero people can destroy your land with explosives.
• randomModifierOnProtectBlock is a random number between 0.0 and 1.0 generated and multiplied with powerUsedToProtectBlock each time it is used to deduct power from the faction for a destroyed block from an explosive so this can lower the amount of power used. I may change the mechanics of this later because the way random numbers work this is likely almost always the same possibly.
• landPowerCostPerHour is hour much a single claim costs per hour
• worldsEnabled allows you to enable the plugin on the specified worlds it is a required parameter
• enabledScanner allows you to enable the lottery based feature to allow (if you win) to get coords to a faction claim or random coords if you lose
• scannerWaitTime is in seconds and enforces a wait time per faction since the scanner is per faction
• scannerChance is a percentage of a chance that it will return the coords to some randomly choosen faction land
• friendlyFire will allow you to enable or disable damage between faction members
• noGriefPerWorld allows you to disable the ability for one faction to claim another faction's land if their power is zero
• powerUsedEachClaim is the amount of power a faction is charged for them to claim land
• numberOfFreeClaims is the number of claims a faction can make for free and afterwards the powerUsedEachClaim takes effect