Bukkit

Installing MC Jobs

Welcome to the install of guide of MC Jobs.

Downloading

The first step is to download the mod. The mod comes in a single jar file. It should not be zipped or have any other files with it. All needed files will be created on first reload or start of the bukkit server.

First Run

MC Jobs will create at least a config.yml on the first run. Before using MC Jobs it is recommended that you go through and edit the config.yml file to your server's needs.

Config YML

For the config.yml file we'll go through it one config option at a time. Starting from the top and working down. This section will be split up into 3 subsections: Top, Jobs, Advanced.

TOP

The top contains the most common items that you would want to change to make your server unique.

• max_pay: -1: Max Pay is how much the server will allow each player to be paid per time_interval. Can help against players that farm incessantly and will help limit the inflow of money into the economy. Use -1 if you want unlimited pay.

• percent_cost: 95 : Percent Cost is designed to allow the charge part of a job to be less than pay. With the default setup this setting is not really relavent because all jobs are either pay only or charge only. However, if you have a job that pays and charges this will make the charge section 95% of what paying would be for the same tier. For example if base pay is 3 then tier 1 would pay 3 and cost 2.85.

• show_pay: true : Show Pay will allow showing payment messages to players. This will keep track of everything a player earns or charges in that time period and send them a message when the time_interval is up.

TIMERS

• time_interval: 60 : It is used to check if a player has manipulated a block in the time period. For example if a player breaks a block at a location they cannot be paid for breaking a block at that location till the time_interval time has past.

• rejoin_interval: 360 : This one is designed to not allow a player to rejoin a job they have quit in the time frame listed. It is also in minutes so this would prevent players from rejoining the job for 6 hours.

• player_save: 15 : The player save interval is for how often should the players file be saved when they are offline. This only effects players that have rejoin timers.

• show_interval: 5 : How often the total pay timers show up and when the max_pay timer is reset.

• delete_cache: 180 : Sets how many days till a player cache file is considered old and should be deleted. This is only done if the advanced section prune is set to true.

MAX_JOBS

This section defines the max amount of jobs a player can have. It is broken up by groups. The groups are defined by your permissions mod and Vault. If you do not have Vault or a permissions mod the only group that matters is the default group. The default group always has to exist for this to work properly. The highest number is always chosen for the player. So if default is set to 4 and Members are set to 3 the players will have 4 jobs. Even the ones in the Members group.

• default: 4 : This is the default amount of jobs everyone is allowed to have. 4 is the config's default.
• Members: 5 : This is an example group called Members. They are allowed to have 1 more job then the default group.
• Admins: 6 : Another group defined for clarity. These can be switched. They follow your permission system groups.

JOBS

This section will explain the structure of how to setup new jobs or modify the existing ones. It will also be broken down by line. We will use example as the job name for ease of explanation.

• example: : All jobs start with their job name. This can be capitalized however you'd like but internally the mod converts all capital characters to lower case. This should work with most languages, but occasionally some unicode characters won't translate properly. If so try not using the capital version and use only lowercase in your job names.

• description: This is an example job. : The description is a description of what the job is. This shows up when a player uses the /jobs example command. If the job name goes over one line of text it will try to wrap properly as to not break up the words. This doesn't effect the job in any way it is just a flavor text.

• basepay: 1.0 : The Base Pay is the starting pay for a job. The Tiers use multiples of this to determine what the job pays when you do an action. When the leveling system is added it will modify the payment further, but base pay is just that. It is the starting point of this jobs pay.

• show_every_time: false : This is the first field that can be omitted if you choose. It will decide whether this job defaults to showing a pay message every time an action is done. The player can still change the default behavior by using /jobs show job_name or /jobs hide job_name. The messages can be turned off for all jobs if you choose to no ill effect to the job.

• exp: 1 : This is a multiplier to how much XP is earned. Values less than 1 mean that it will take a player longer to level a job while values greater than 1 earn XP faster. A value of 0 means XP cannot be earned in this job. So no leveling, however the player is always considered level one.

• default: false : This determines whether a job is a default job or not. Default jobs are automatically given to players on join unless they have the mcjobs.admin.leavedefault permission. If you made all jobs default any player joining would have every job in the game. Currently default jobs are used to charge players for various actions. Thus making the actual paying jobs more desirable.

• break: : Break is one of the 8 choices you have to pay for. Break stands for breaking blocks. This will pay when a player breaks the specific block listed.

• place: : Place is one of the 8 choices you have to pay for. Place stands for placing blocks. This will pay when a player places a specific block in the game world.

• defeat: : Defeat is one of the 8 choices you have to pay for. Defeat stands for killing mobs or potentially players in the game world. This will pay when you kill the listed entity.

• craft: : Craft is one of the 8 choices you have to pay for. Craft stands for crafting objects. This will pay when you craft an object using a furnace, crafting station or your own crafting square. This will pay when you craft the listed item.

• repair: : Repair is one of the 8 choices you have to pay for. Repair stands for repairing objects. This can pay for using the built in repair, putting two of the same item in the repair square, or if you have mcMMO it will pay on an mcMMO repair using an anvil.

• fishing: : Fishing is one of the 8 choices you have to pay for. Fishing stands for using a fishing pole to catch something. Any entity can be put into this field. So if you put creeper you will be paid for casting your bobber at a creeper. DROPPED_ITEM is what the bukkit team considers a fish.

• potions: : Potions is one of the 8 choices you have to pay for. Potions are what are created by using a brew stand. Look at the potion page to see all the allowable potions that can be made.

• enchant: : Enchant is one of the 8 choices you have to pay for. Enchants are created by using an enchanting block. Look at the enchant page to see all the allowable enchants that can be done.

• pays: true : Pays true means that this action will pay the player. If pays is set to false then it will charge a player. An action, like break or place, can only either pay or charge not both for an individual job.

• hide: false : Using the command /jobs example you'll notice there's a lot of generated text. The file size chat window is only 14 lines long. If you have a job that pays and charges for the exact same blocks. For example in our job example job we could have dirt pay when broken and dirt also pay when placed, you could set the place section to hide: true. This way it doesn't show up when a player uses the command /jobs example. If you hide everything it won't show the player what they get paid for! Most the time you'll want to leave this at false.

• tier1: dirt : I'm going to group the five tiers into this one explanation. As mentioned under base pay the tiers modify the pay amount by a multiplier. Tier1 pays base pay X 1. Tier2 pays base pay X 2. Tier 3 pays base pay X 3 and so on. This goes up to Tier 5. Dirt is what we are paying for. You always list items with a space in between them. The place, break, craft, and repair tiers use the built in Materials list. The defeat and fishing tiers use the built Entity list. Potions use a custom list. Enchant is not yet implemented.

This concludes the jobs section. With this you should be able to build any job you choose.

RANKS

The rank system is used for the leveling system. This is completely dynamic and you can choose whatever level and whatever rank name you want. The only one that has to exist is a rank that represents level 1. Also no spaces are allowed in the rank names.

• novice: 1 : As stated the only rank required
• beginner: 10
• adept: 20
• professional: 50
• veteran: 100
• expert: 250
• master: 500
• grandmaster: 1000 : The last default rank. If you wanted you could have a rank every hundred levels or 50 levels, or every level for that matter. It's added as rank name : rank level required. No spaces are allowed in the rank names!

BACKEND

This will determine the type of backend the mod uses for saving information about players and their jobs.

• type: file : File is the default backend. All user data is saved to player.dat files. Rejoin timers are saved to perms.db. It is the only currently available backend.
• user: user : When SQL is released will be the username to authenticate to the SQL server.
• pass: password : When SQL is released will be the password to authenticate to the SQL server.
• database: sql : The database name that the user and password will try to connect to.
• host: localhost : The host machine that has the SQL databases.
• port: 3306 : 3306 is the default port SQL uses. If you changed it, you can change the port connection here.

ADVANCED

Advanced includes most of the important setup settings to MC Jobs. This modifies the way the mod works while the TOP settings modifies what the players can do and when.

• language: english : Sets the language option for the text. Currently the only built in choices are English and French. As people send me language files I will add more into the plugin. You can also set it to custom. This will create a custom.yml file in your mcjobs folder. You can then edit this file and change the text yourself to say whatever you'd like. This way you can customize the text to your world. For example say your Minecraft world doesn't have Iron Ore it has Adamantium Ore. In the custom.yml file you'd go down to the materials section and change Iron Ore to Adamantium Ore and when a player does /jobs miner it will now say Adamantium Ore.

• usePerms: false : For ease of use of the plugin I designed it with someone having no server admin experience in mind. If you leave usePerms to false MC Jobs will assume you have no permission mod and default to the bukkit system. OPs will get the admin commands and everyone else will have access to the player commands. Switching usePerms to true requires that you have a permission mod on your server.

• multiWorld: false : This option is there if you want to limit jobs use per world. It defaults to false which means players can do everything in every world. If set to true then it requires the player to have the mcjobs.world.world_name permission trees.

• payment_type: money : The mod automatically tries to pay in money first. If no economy bridge is found it will default to paying in xp only. Valid choices for this are: money, xp, both. If you don't want to pay in money use xp. If you want to pay both xp and money use both.

• payment_mod: vault : The mod tries to find vault. If you don't have it you can change it to none. Or if you'd like you can use register.

• pay_scale: 1 : A multiplier to how much money or in game XP is earned for doing actions. This multiplier is across the board. So if you make it 10 everything will pay 10 times as much as it normally does.

• log_mod: none : This chooses which block logging mod you'd like to use. The only choices now are: none and logblock .

• xp_modifier: 10 : This is a multiplier to how much xp is needed to level. 10 is the default. If you would like faster leveling gains then lower the multiplier to less than 10. If you want it to take longer make it larger than 10.

• pay_spawners: false : When set to false this will not pay kills within a certain radius of a spawner. The radius determine is from the mob's death location. If set to true this will pay all kills regardless of proximity to spawners.

• spawn_distance: 8 : This is the distance that pay_spawners will check. Larger numbers are harder on the server's resources as it checks every block in the radius (in this case 8). 8 should be sufficient for most servers, but if you have some serious hardware you could probably safely bump it up to 16. Much more than that will cause severe lag as the the checker currently runs in the main thread.

• nopitch: false : If set to true this will turn off the pitch to new players that can join jobs on the server.

• prune: false : If set to true the mod will delete old user files using the delete_cache timer to determine how old the file needs to be in order to be deleted.

• version: 3100 : Current version of the mod's config file. Used mainly to give warning messages. Should not be changed by the user.

Setting up for paying in money instead of xp

MC Jobs should try to pay in money from the get go. As long as you have vault and an economy mod it will work.

Changing the language

Starting with the 2.5 update localization is now possible. Inside the config.yml file change language: english to one of these options:

• english
• french
• french_alt
• dutch
• russian
• russian_alt
• chinese
• chinese_alt
• spanish
• spanish_alt
• custom

If any of the language files don't work you can try the alt version.

More languages on the way

If your language is not yet supported you can choose custom. That will create a file called custom.yml to be added to your mcjobs data folder in the plugins directory. From there you can edit the file. You should be able to edit the file in your local character map (ASCII for US, ISO-8559-1 for Europe). UTF-8 works as well, but occasionally there's errors with the way some linux distros handle UTF-8 with java. If you get an unknown character error on the mod load remove the offending character and replace it with one that isn't a special character.

Using the /mcjobsadmin Command - /jadm

/jadm list [player/group]

Lists all the jobs that the player or group of players have.

/jadm add [player/group] [job]

Adds the job to the player or group of players.

/jadm remove [player/group] [job]

Removes the job from the player or group of players if they have the job.

/jadm addlevel [player/group] [job] [number of levels]

Adds levels to the job for the player or group of players as long as they have the job.

/jadm addxp [player/group] [job] [number of levels]

Adds experience to the job for the player or group of players as long as they have the job.

/jadm reload

Reloads the config.yml and jobs.yml.

Using the /mcjobs Command - /jobs

/jobs list

Jobs list will show all the jobs available on the server and how many jobs you currently have along with how many more you can join. It will also show you which jobs are default jobs.

/jobs join job_name

Use this command to join a job. Job_name is not case sensitive. So DIGGER is the same as digger which is the same as DiGgEr. If the jobs list shows the name is dark gray you cannot join it.

/jobs leave job_name

Use this command to leave a job. Job_name is not case sensitive. So DIGGER is the same as digger which is the same as DiGgEr. When you leave a job it will create a timer that you'll have to wait before you can join the job again.

/jobs job_name

This shows detailed information about the job. It tells you what blocks it pays and charges for. Also how much you get paid and charged. It will also tell you the level and experience points you have in the job.

/jobs show job_name

This will show pay messages every time you perform and action that the job pays or charges for.

/jobs hide job_name

This will hide pay messages every time you perform and action that the job pays or charges for.

Conclusions

This should give you all the information you need to have to setup and maintain MC Jobs. If you have any questions please post in the forums.