EpicKnarvik97
a5ae3cb295
All checks were successful
EpicKnarvik97/Blacksmith/pipeline/head This commit looks good
201 lines
19 KiB
Markdown
201 lines
19 KiB
Markdown
# Blacksmith
|
|
|
|
The blacksmith plugin adds a new blacksmith trait to Citizens NPCs. NPCs are able to repair a player's held item for a
|
|
fee. Costs are highly customizable.
|
|
|
|
### Important changes from the original fork
|
|
|
|
- The problem with armor being unrepairable because the player would equip it instead has been fixed.
|
|
- A lot of configuration value have had their paths altered, so configurations need to be updated.
|
|
- By default, natural cost is used. The original fork made it cheaper the more damaged an item is, but natural cost
|
|
makes the cost increase the more damaged the item is.
|
|
- EnchantmentTarget is used instead of a hard-coded list of repairable items
|
|
- All settings (except default reforge-able-items), both global and for each blacksmith, can be changed using commands,
|
|
and support tab-completion.
|
|
- This plugin is not directly compatible with the original. If you are using the old one, you will need to set it up
|
|
again!
|
|
|
|
### Dependencies
|
|
|
|
- Citizens2
|
|
- Vault
|
|
- Any Vault-supported Economy plugin
|
|
|
|
## Basic usage
|
|
|
|
To create a new blacksmith, simply add the blacksmith trait to an NPC by selecting it with `/npc select`, and then using
|
|
`/trait add Blacksmith` (See Citizens' documentation for more details).
|
|
|
|
Right-clicking the NPC will tell you if the currently held item is repairable by the blacksmith. If it is, the
|
|
blacksmith should give a price quote. Right-clicking
|
|
again starts the repair. The item should be given back or dropped after a random delay according to the set limits.
|
|
|
|
While costs are always set globally (no blacksmith can do the same job for cheaper), the blacksmith's messages,
|
|
cool-down between each reforge, whether the item is dropped or given, the chance of failing or adding an enchantment,
|
|
the maximum number of added enchantments, max and min delays, the length of the cool-down and which items the blacksmith
|
|
is able to reforge can be changed individually.
|
|
|
|
Also note: As a change from the original plugin, unless a value for an NPC has been explicitly set for that NPC, it will
|
|
mirror the values set in config.yml. This also means that configuration values aren't populated automatically in
|
|
citizen's NPC save file. While you can manually set the values using the same keys as in config.yml, you should use the
|
|
/blacksmith command when possible.
|
|
|
|
### Special behavior
|
|
|
|
In addition to just being able to repair items, blacksmiths have some random features which can be cool or annoying:
|
|
|
|
- There is a chance that blacksmiths fail to repair an item, leaving it at about the same durability as before. Use
|
|
failReforgeChance to control the chance. Set it to 0 to remove the feature.
|
|
- There is a chance a blacksmith may add an enchantment to a reforged item. You can control the probability using
|
|
extraEnchantmentChance, and set the maximum number of enchantments using maxEnchantments
|
|
|
|
## Commands
|
|
|
|
| Command | Arguments | Description |
|
|
|-------------------|-------------------------------|----------------------------------------------------------------------------------------------|
|
|
| /blacksmith | \<option> \[new-value] | Changes a configuration option for the selected blacksmith (use Citizens' /npc select first) |
|
|
| /blacksmithconfig | \<reload/option> \[new-value] | Changes a default/global configuration value |
|
|
| /preset | \<preset>\[:filter] | Displays all materials included in the given preset, after applying the filter if set |
|
|
|
|
For /blacksmith and /blacksmithconfig, if a new value isn't specified, the current value is displayed instead.
|
|
|
|
For /blacksmith, using -1 or null as the value will clear a custom value, making the NPC use the default value set in
|
|
the config instead. Additionally, every value overridden for an NPC will display a marker (default: \[NPC]) when
|
|
displaying the current value.
|
|
|
|
Note: basePrice, pricePerDurabilityPoint and enchantmentCost can be set like: `/blacksmithconfig option 4` or
|
|
like `/blacksmithconfig option material/enchantment 4` depending on whether you are setting the default or an override
|
|
for a specific material/enchantment. For /blacksmithconfig <basePrice/pricePerDurabilityPoint/enchantmentCost> <
|
|
material/enchantment>, using -1 or null as the value will clear the cost for the specified material/enchantment, using
|
|
the default one instead.
|
|
|
|
### Presets and filters:
|
|
|
|
**Presets are a nice way to make specialized blacksmiths by specifying categories of materials, instead of manually
|
|
listing every material manually. They can only be used for the `reforgeAbleItems` option.**
|
|
|
|
Note: All of these can be used when specifying reforge-able items, such as
|
|
"preset:weapon-smith:bow,preset:armor_smith:gold,PRESET:TOOL_SMITH,shield"
|
|
|
|
The format of reforge-able items requires each preset/material to be separated by a comma. If specifying a preset
|
|
instead of a material, start by typing "preset:". Then you can type WEAPON_SMITH, ARMOR_SMITH or TOOL_SMITH. If you
|
|
want, you can add another colon and one of the filters supported by the preset. For example: "preset:WEAPON_SMITH:BOW"
|
|
to make the blacksmith only repair bows. You can use the same preset several times with different filters. For
|
|
example: "preset:ARMOR_SMITH:DIAMOND,preset:ARMOR_SMITH:NETHERITE" would allow the blacksmith to repair all diamond and
|
|
netherite armor.
|
|
|
|
Presets and filters can also be negated by applying a "-" character in front of the material name. For example,
|
|
"-SHIELD" would make shields unrepairable, even if included in a preset. "preset:WEAPON_SMITH,-SHIELD"
|
|
would allow the blacksmith to repair any weapon included in the WEAPON_SMITH preset except shields.
|
|
"preset:BLACKSMITH,-ELYTRA"would allow the blacksmith to repair any repairable item, except elytra.
|
|
|
|
All currently supported presets, and available filters for each preset:
|
|
|
|
- BLACKSMITH (WEAPON_SMITH + ARMOR_SMITH + TOOL_SMITH)
|
|
- WEAPON_SMITH: (RANGED + SWORD + SHIELD)
|
|
- BOW (bows and crossbows)
|
|
- SWORD (swords)
|
|
- RANGED (bows, crossbows and tridents)
|
|
- ARMOR_SMITH: (HELMET + BOOTS + LEGGINGS + CHESTPLATE + ELYTRA)
|
|
- LEATHER (all pieces of leather armor)
|
|
- IRON (all pieces of iron armor)
|
|
- CHAINMAIL (all pieces of chainmail armor)
|
|
- GOLD (all pieces of gold armor)
|
|
- DIAMOND (all pieces of diamond armor)
|
|
- NETHERITE (all pieces of netherite armor)
|
|
- HELMET (all helmets)
|
|
- BOOTS (all boots)
|
|
- LEGGINGS (all leggings)
|
|
- CHESTPLATE (all chest-plates)
|
|
- TOOL_SMITH: (PICKAXE + AXE + HOE + SHOVEL + MISC)
|
|
- WOOD (all wood tools)
|
|
- STONE (all stone tools)
|
|
- IRON (all iron tools)
|
|
- GOLD (all gold tools)
|
|
- DIAMOND (all diamond tools)
|
|
- NETHERITE (all netherite tools)
|
|
- PICKAXE (all pickaxes)
|
|
- AXE (all axes)
|
|
- HOE (all hoes)
|
|
- SHOVEL (all shovels)
|
|
- MISC (FISHING_ROD + SHEARS + FLINT_AND_STEEL)
|
|
|
|
## Permissions
|
|
|
|
| Permission node | Description |
|
|
|------------------|----------------------------------------------------------|
|
|
| blacksmith.admin | Allows overall blacksmith configuration |
|
|
| blacksmith.edit | Allows changing settings for the selected blacksmith NPC |
|
|
| blacksmith.use | Allows the player to repair items using blacksmiths |
|
|
|
|
## Configuration options
|
|
|
|
### Plugin Options
|
|
|
|
| Key | Value type | Description |
|
|
|----------|------------|----------------------------------------------------------------------------------------------|
|
|
| language | string | The language used for this plugin. Only "en" is supported, unless you add a custom language. |
|
|
|
|
### Global-only options
|
|
|
|
| Key | Value type | Description |
|
|
|-------------------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| basePrice | positive decimal number | The base price which has to be paid regardless of the durability remaining for an item. Setting this without specifying a material sets the basePrice for any item the basePrice has not been set for. |
|
|
| pricePerDurabilityPoint | positive decimal number | The price added for each durability point present/missing (depends on whether natural cost is set to true or false). Setting this without specifying a material sets the pricePerDurabilityPoint for any item the pricePerDurabilityPoint has not been set for. |
|
|
| enchantmentCost | positive decimal number | The added cost for each level of an enchantment present on the item. The cost can be set for specific enchantments. Not specifying an enchantment sets the value for all enchantments without a set value. |
|
|
| useNaturalCost | true/false | If true, each missing durability will add to the cost (price = basePrice + missingDurability * pricePerDurabilityPoint + enchantmentCost). If false, durability will be used to calculate the cost instead of missingDurability (this was the behavior before natural cost was added). |
|
|
| showExactTime | true/false | If true, blacksmiths will display exact time remaining in minutes and seconds, instead of vague expressions |
|
|
|
|
### Per-npc (with default values set in config.yml)
|
|
|
|
#### Configuration values
|
|
|
|
| Key | Value type | Description |
|
|
|------------------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| dropItem | true/false | Whether the blacksmith should drop the repaired item on the ground (instead of putting it into the player's inventory). |
|
|
| disableCoolDown | true/false | Whether to completely disable the cool-down between repairs. |
|
|
| disableDelay | true/false | Whether to completely disable the delay required to reforge an item. |
|
|
| failReforgeChance | 0-100 | The chance of the blacksmith failing to repair an item. |
|
|
| extraEnchantmentChance | 0-100 | The chance of the blacksmith adding an enchantment to an item. |
|
|
| maxEnchantments | 0-10 | The maximum number of different enchantments a blacksmith can add. |
|
|
| maxReforgeDelay | 0-3600 | The maximum number of seconds a player needs to wait for an item to be repaired. |
|
|
| minReforgeDelay | 0-3600 | The minimum number of seconds a player needs to wait for an item to be repaired. |
|
|
| reforgeCoolDown | 0-3600 | The cool-down, in seconds, a player has to wait between each time they use one specific blacksmith. |
|
|
| reforgeAbleItems | DIAMOND_LEGGINGS,GOLD-pickaxe,bow, etc. | Specifies which items this blacksmith is able to reforge. If set to "" or null, all normally repairable items can be repaired. If set to a list of items, only the items specified can be repaired. Some presets have been included for ease of use. Use a preset by specifying "preset:sword-smith" instead of a material such as "gold-pickaxe". |
|
|
| blacksmithTitle | text string | The title displayed as part of the message explaining that a blacksmith doesn't recognize a player's held item |
|
|
| enchantmentBlocklist | string list | A string list of all enchantments a blacksmith should not be allowed to add to items. |
|
|
|
|
#### Messages
|
|
|
|
| Message Key | Explanation |
|
|
|--------------------------|-----------------------------------------------------------------------------------------------------------------|
|
|
| busyPlayerMessage | The message displayed when the blacksmith is serving another player |
|
|
| busyReforgeMessage | The message displayed when the blacksmith is busy reforging an item |
|
|
| coolDownUnexpiredMessage | The message displayed when the player has to wait for the cool-down to expire before using the blacksmith again |
|
|
| costMessage | The message displayed when telling a player about the cost of repairing an item |
|
|
| failReforgeMessage | The message displayed when a blacksmith fails to reforge an item |
|
|
| insufficientFundsMessage | The message displayed when a player is unable to pay for reforging an item |
|
|
| invalidItemMessage | The message displayed when a blacksmith is presented an item which it cannot repair |
|
|
| itemChangedMessage | The message displayed when a player changes their item after being shown the repair cost |
|
|
| startReforgeMessage | The message displayed when a blacksmith starts reforging an item |
|
|
| successMessage | The message displayed when a blacksmith successfully repairs an item |
|
|
| notDamagedMessage | The message displayed if a player tries to reforge an item with full durability |
|
|
|
|
## Language customization
|
|
|
|
All strings, even time units, are customizable. If you place a strings.yml file in the plugin folder, it will take
|
|
priority over built-in languages. If you want to change strings, look at Blacksmith/src/main/resources/strings.yml for
|
|
the proper keys. All strings have the format: ENUM: "Displayed string". The enum must be identical as it defines which
|
|
string you have changed. All strings belonging to a language are beneath the language code and indented with two spaces.
|
|
|
|
The easiest way to add a new language is to copy an existing language and paste it into your custom strings.yml and
|
|
change strings as necessary. If you don't include all strings, the remaining will use the built-in English translation.
|
|
Remember to change the language code to whichever you use for your custom language.
|
|
|
|
The interval messages are unique in that if several values are separated by comma (option1,option2,option3), a random
|
|
message will be chosen each time it's displayed.
|
|
|
|
## License
|
|
|
|
Blacksmith is licensed under the GNU Public License Version 3.0. This includes every source and resource file. See the
|
|
HEADER file for a more detailed license description. |