PaidSigns/README.md

11 KiB

Paid signs

The paid-signs plugin is a plugin that lets you add costs for creating plugin signs. This allows restricting usage of signs such as CraftBook's gate/lift and other signs while still allowing every player to create the signs.

Note: OP players, and players with the '*' permission will have the paidsigns.paymentexempt permission and will not see any payment messages. For testing, you'll need to un-set the paidsigns.paymentexempt permission.

Limitations

As this plugin only listens to sign change events, there are some limitations:

  1. The plugin is not aware of whether the creation of a sign is successful. Setting the appropriate permission might help, but it's not guaranteed
  2. It is assumed that any protection plugins run before this plugin checks a sign, but it's not guaranteed
  3. Plugins changing the lines on signs when successful might create confusion and mismatches if changes happen before this plugin checks a sign

FAQ

A player placed down a sign, but some plugin broke it afterwards. What do I do?

There are three ways this can be solved:

  1. Make the player (or anyone else) place an empty sign in the same location and break it again. The player should be refunded as long as refunds are enabled.
  2. Reload PaidSigns. The player should be refunded as long as refunds are enabled.
  3. Restart the server. The player should be refunded as long as refunds are enabled. Never place a new paid sign in the same location in this situation, as the old sign will be overwritten, and the ability to refund the player automatically will be lost.

Players have to pay for signs, even if the plugin sign isn't created

This is a known limitation of this plugin. As long as this plugin is agnostic to the plugin signs it's used for, it cannot really know if a plugin sign has been created. The best you can do is finding the permission required for the plugin sign and specifying it when creating the paid sign. It can be assumed that the player is able to create the plugin sign, if the player has the correct permission.

How can this plugin be used to enhance a server?

This plugin is known to be helpful with two tasks:

  1. Allow normal players to create plugin signs, such as CraftBook's elevator signs, but at a cost. This can be done by simply specifying the exact text required for the plugin sign in the paid sign conditions.
  2. Add a swearing jar/swearing filter to the server. This can be done with a paid sign matching ANY condition, where the list of swear words is given as a regEx. The same regEx should be added for each of the four sign lines.

Custom parser

Before anything else, it's important to note that as an experiment, I used a custom command-parser for this plugin. This means that sign names can contain spaces, as long as the name is in quotes. In most cases, this actually works fine, even though it differs a lot from the default behavior, but if you tab-complete the first word in the name first, and then try to tab-complete the rest, tab-completion will fill in the second world with the entire name, which is unfortunate. That's really just how tab-completion works, and not something I think I can do anything with.

Commands

An argument marked by "<>" is required to execute the command. An argument marked by "[]" is optional. For empty arguments, such as no paid sign permission, you should use empty quotes ("").

Command Arguments Permission Description
/paidsigns paidsigns.info Used to display in-game information about all other commands
/addpaidsign <name> <cost> [permission] [ignore case] [ignore color] [match any condition] paidsigns.manage Used to add a new paid sign
/addpaidsigncondition <name (of a paid sign)> <line number> <string to match> [executeRegEx] [ignoreCase] [ignoreColor] paidsigns.manage Used to add a condition to a paid sign
/listpaidsigns [name (of a paid sign)] [line number] paidsigns.manage Used to list registered paid signs or a registered paid sign's conditions
/editpaidsign <sign name> <property>/<line number> [new value]/<property> [new value] paidsigns.manage Used to modify a registered paid sign or one of its conditions
/removepaidsigncondition <name (of a paid sign)> <line number> paidsigns.manage Used to remove a condition from a registered paid sign
/removepaidsign <name (of a paid sign)> paidsigns.manage Used to remove a registered paid sign
/reload paidsigns.reload Used to reload the configuration file

Command explanation

/addpaidsign

This command adds a new paid sign that does nothing until a condition is added.

/addpaidsign <name> <cost> [permission] [ignore case] [ignore color] [match any condition]

Argument Usage
name A recognizable name only used to differentiate between registered paid signs
cost The cost a player needs to pay to create any sign matching the paid sign
permission If the paid sign is used to represent a plugin sign, the permission should be the permission necessary for creating the plugin sign. This is used to decide if the plugin sign was created, or if the player was denied.
ignore case Whether any conditions of the paid sign should ignore case by default, when matching against text (default uses the config file value).
ignore color Whether any condition of the paid sign should ignore color by default, when matching against text (default uses the config file value).
match any condition Whether to trigger a paid sign match if a single one of the sign's conditions is true. This is mainly useful if several lines may contain the match string, or if trying to match a word.

/addpaidsigncondition

This adds a condition to a paid sign which is used to decide if a sign created by a player matches the paid sign. Adding a paid sign condition to a line that already has one will replace the previous condition.

/addpaidsigncondition <name (of a paid sign)> <line number> <string to match> [executeRegEx] [ignoreCase] [ignoreColor]

Argument Usage
name The name of the paid sign to add the condition to
line number The line on the sign (1-4) to search for any matches
string to match The string or regular expression to look for on a sign
executeRegEx Whether to use a regular expression match instead of looking for the exact string
ignoreCase Whether this condition should ignore case when trying to match the string (default uses the "parent" sign's value)
ignoreColor Whether this condition should ignore color when trying to match the string (default uses the "parent" sign's value)

/listpaidsigns

This lists registered paid signs and paid sign conditions. No arguments will print a list of paid signs

/listpaidsigns [page number]/[name (of a paid sign)] [line number]

Argument Usage
page number Paid signs are listed 7 at a time, so the page number is used to see the next 7
name The name of the paid sign to see information about
line number The line number of the condition to see information about

/editpaidsign

This command changes a property of a paid sign or a paid sign condition

/editpaidsign <sign name> <property>/<line number> [new value]/<property> [new value]

Argument Usage
name The name of the paid sign to edit
property / line number The property to edit for the sign (name, cost, permission, ignoreCase, ignoreColor, matchAnyCondition), or the line of the condition to edit
new value / property The new property value if a property was specified in the second argument, or a condition property (stringToMatch, executeRegEx, ignoreCase, ignoreColor) if a line number was specified in the second argument
new value The new property value of the condition property specified in the third argument

/removepaidsigncondition

Removes a paid sign condition from a sign

/removepaidsigncondition <name (of a paid sign)> <line number>

Argument Usage
name The name of the paid sign to remove the condition from
line number The line the condition is associated with

/removepaidsign

Removes a registered paid sign

/removepaidsign <name (of a paid sign)>

Argument Usage
name The name of the paid sign to remove

Permissions

Node Description
paidsigns.* Grants all paid signs permissions
--paidsigns.manage Grants the permission to add/remove a paid sign
--paidsigns.reload Grants the permissions to reload the plugin
--paidsigns.paymentexempt Makes this player exempt from the cost of paid signs

Configuration options

Option Description
language The language to use for all messages displayed to players. Currently, only "en" is valid.
ignoreCase Whether to ignore the case (lowercase/uppercase) of the paid sign text. The option can be set on a per-sign basis, but this value is used if not specified. The correct value depends on whether the plugin signs it should match are case-sensitive or not.
ignoreColor Whether to ignore any color or formatting applied to the text when trying to match a paid sign's text. The option can be set on a per-sign basis, but this value is used if not specified. The correct value depends on whether the plugin signs it should match allow coloring or not.
refundsEnabled Whether to enable refunds to the sign creator when a sign detected as a paid sign is broken (payment will always go to the original creator)
refundPercentage The percentage of the paid sign cost to refund (0-100)
refundAlways Whether to refund when signs that players have paid for are broken by anything. This includes tnt, creepers, pistons and similar

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 PaidSigns/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.

License

PaidSigns 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.