Skip to content

[3] OpenRP Descriptions. How do I set it up?

Jump to bottom
Bozga Rareș Ionuț edited this page Dec 28, 2020 · 10 revisions

OpenRP Descriptions Set-up.

For the sake of simplicity, OpenRP Descriptions will be referred to as simply Descriptions from now on.
Note that anywhere where a player's character is mentioned means it has to do with OpenRP Descriptions, even if not on this specific Wiki page.

What commands does Descriptions add, and how do I use them?
Descriptions brings a single powerful command to the table: /character.

The /character command has several ways in which it can be used:

/character
This will display the character field changer. The field changer lets players change their own fields, such as their name, description, gender...
To use the field changer, one must open the chat to click on the buttons.

/character set (field) (value)
(requires use-perm permission found in Descriptions' config)
This command is used by players to set one of their fields, such as their name, description, gender... to a certain value.
For example, you might do /character set name M. Notch Persson to set your character's name!
In fact, you can observe that the /character field changer simply auto-completes the command for you, so players needn't remember it.

/character check (user)
(requires check-perm permission found in Descriptions' config)
This will display the information of a player according to the description-format found in Descriptions' config.

/character override (user) (field) (value)
(requires override-perm permission found in Descriptions' config)
This command can be used by staff to forcefully change one field of a specific player.
This is useful if a field is locked, or if a player has set a field to some value that breaks the rules.

Great, but is there a way for me to add custom fields?
Yes, there is! This is where the true usefulness of Description shows.
First, let's take an example. The default configuration:

# OpenRP Descriptions

use-perm: orpdesc.set
override-perm: orpdesc.override
check-perm: orpdesc.check
bypass-cooldown-perm: orpdesc.bypasscooldown

fields:
   name:
      allowed-values:
         type: contains
         case-sensitive: false
         value: "abcdefghijklmnopqrstuvwxyz.-' "
      length:
         minimum: 3
         maximum: 24
      color-code-perm: orpdesc.name.color
      cooldown: 10
      default-value: <?>
   description:
      allowed-values:
         type: without
         case-sensitive: false
         value: null
      length:
         minimum: 3
      color-code-perm: orpdesc.desc.color
      cooldown: 10
      default-value: No description set
   gender:
      allowed-values:
         type: list
         case-sensitive: true
         value:
         - Male
         - Female
         - Other
      color-code-perm: orpdesc.desc.color
      cooldown: 10
      default-value: Other
   race:
      allowed-values:
         type: locked
      default-value: Human

right-click-player-to-view-description: true
must-crouch-to-view-description: true

description-format:
- "&e{player}'s &aDescription:"
- "&bName: {orpdesc_name}"
- "&bGender: {orpdesc_gender}"
- "&bRace: {orpdesc_race}"
- "&bDescription:"
- "&f{orpdesc_description}"

Let's take the name field separately, and explain what each option does. This is the structure of a field in general:

name:
  allowed-values:
     type: contains
     case-sensitive: false
     value: "abcdefghijklmnopqrstuvwxyz.-' "
  length:
     minimum: 3
     maximum: 24
  color-code-perm: orpdesc.name.color
  cooldown: 10
  default-value: <?>

We can identify the field by its identifier, name. Each option has a meaning:

allowed-values
This section contains several values, all of which are used to tell OpenRP what a player is allowed to set in this field.
For example, if you have an age field, you might only want players to use numbers, if you have a race field, you might only want players to use specific races from a list, and so on...

The allowed-values section contains the following:

type
Can only be contains, without, list, and locked.
The type of the value can be summarized like so:

  • contains means that the text you have must only contain the letters/numbers/symbols from value.
  • without is the opposite of contains, which means the text you supply must NOT contain the letters/numbers/symbols from value.
  • list is a way of forcing specific values that must be picked by the player, which is to say the player must enter text that can be found in the value list.
  • locked means the player is not allowed to change this field whatsoever, and only by using /character override the value can get changed.

case-sensitive
If this is true, then it means the following:

  • if type: contains, then the letters from value are checked if they are lowercase or UPPERCASE.
  • if type: without, it's the same as contains, meaning the letters are checked to be lowercase or UPPERCASE.
  • if type: list, it means that the player must type one of the values from the value list EXACTLY, or it won't work.
  • if type: locked then this makes no change.

If this is false, then it means the following:

  • if type: contains, then the letters from value can be either lowercase and UPPERCASE, and any will work fine.
  • if type: without, it's the same as contains, meaning the letters can be either lowercase and UPPERCASE, and any will work fine.
  • if type: list, it means that the player can type one of the values from the value list lowercase or UPPERCASE, yet it will still work.
  • if type: locked then this makes no change.

value
Depending on the type, the value can look like this:

  • if type: contains, then you must write all the allowed letters/numbers/symbols.
    For example, if you only wanted players to be able to use numbers, you would type
value: '0123456789'
  • if type: without, then you must write all the letters/numbers/symbols which are prohibited. For example, if you wanted to let the players type anything BUT exclamation and question marks, you would type
value: '!?'
  • if type: list, then you must make a list of all the possible things a player can type.
    For example, if you only wanted to let players pick three specific races, you would type
value:
- Human
- Elf
- Orc
  • if type: locked then you can ignore value since it won't matter.

length This section contains two values which explain how short/long a value has to be for it to be accepted.
If type: list or type: locked, this has no effect.

The length section contains the following:

minimum
This number represents the minimum amount of letters/number/symbols for a field.
You can set this to 0 or just remove it entirely to have no minimum length.

maximum
This number represents the maximum amount of letters/number/symbols for a field.
You can just remove it entirely to have no maximum length.

color-code-perm
This permission node checks if a player is allowed to use color codes in their field (color codes get automatically removed otherwise).

cooldown
This number represents the time in seconds a player has to wait before they set a specific field again.
This can be useful so a player doesn't change their values too often in order to troll.

default-value
This text can be set to anything, even if it doesn't match the allowed-values conditions, and it will be used to set a player's default value for this specific field when they log into the server for their first time (or if their data was lost somehow).

Now, armed with this knowledge, let's go ahead and create our own custom field!
The example below is for a custom realm field.

realm:
  allowed-values:
    type: list
    case-sensitive: true
    value:
    - Southern Hyrule
    - Northern Hyrule
    - Vallachia
    - Alterra
  color-code-perm: orpdesc.desc.color
  cooldown: 10
  default-value: Alterra

Let's also not forget to change a player's description format, so that other players can see his realm!
You can get the player's current realm using {orpdesc_realm}!

description-format:
- "&e{player}'s &aDescription:"
- "&bName: {orpdesc_name}"
- "&bGender: {orpdesc_gender}"
- "&bRace: {orpdesc_race}"
- "&bRealm: {orpdesc_realm}"
- "&bDescription:"
- "&f{orpdesc_description}"

Now, let's add our field & new description format to our configuration. This is what we end up with, full:

# OpenRP Descriptions

use-perm: orpdesc.set
override-perm: orpdesc.override
check-perm: orpdesc.check
bypass-cooldown-perm: orpdesc.bypasscooldown

fields:
   name:
      allowed-values:
         type: contains
         case-sensitive: false
         value: "abcdefghijklmnopqrstuvwxyz.-' "
      length:
         minimum: 3
         maximum: 24
      color-code-perm: orpdesc.name.color
      cooldown: 10
      default-value: <?>
   description:
      allowed-values:
         type: without
         case-sensitive: false
         value: null
      length:
         minimum: 3
      color-code-perm: orpdesc.desc.color
      cooldown: 10
      default-value: No description set
   gender:
      allowed-values:
         type: list
         case-sensitive: true
         value:
         - Male
         - Female
         - Other
      color-code-perm: orpdesc.desc.color
      cooldown: 10
      default-value: Other
   race:
      allowed-values:
         type: locked
      default-value: Human
   realm:
      allowed-values:
          type: list
          case-sensitive: true
          value:
          - Southern Hyrule
          - Northern Hyrule
          - Vallachia
          - Alterra
      color-code-perm: orpdesc.desc.color
      cooldown: 10
      default-value: Alterra

right-click-player-to-view-description: true
must-crouch-to-view-description: true

description-format:
- "&e{player}'s &aDescription:"
- "&bName: {orpdesc_name}"
- "&bGender: {orpdesc_gender}"
- "&bRace: {orpdesc_race}"
- "&bRealm: {orpdesc_realm}"
- "&bDescription:"
- "&f{orpdesc_description}"

VERY IMPORTANT: You must keep the spacing the same! YAML is a language that is sensitive to spaces and line breaks.

Now, you can use OpenRP to reload the Descriptions changes: /openrp reload descriptions.
Of course, if any players are online, the plugin might encounter unknown errors, because players will lack the new field.
A player's fields are checked only when they relog onto the server so that lag is avoided.
Therefore, you either get everybody online to log back on the server, or you restart the server so they get kicked off automatically.

That is basically it! You know now how to add your own custom fields to OpenRP!
Of course, you can remove any of the pre-made fields & only have the ones you actually need.

You can use the new field in other plugins via PlaceholderAPI or MVdWPlaceholderAPI like so:

  • PlaceholderAPI: %orpdesc_(field)% (e.g. %orpdesc_realm%)
  • MVdWPlaceholderAPI: {orpdesc_(field)%} (e.g. {orpdesc_realm})

What about the other stuff from config.yml?
The rest is pretty simple, and is much easier to understand.

use-perm, override-perm, check-perm
All these 3 permissions are used in the /character command. Check the command at the top of this page!

bypass-cooldown-perm
Players that have this permission will ignore the cooldown times set for all the fields.
This might be useful command for trusted members, staff members, or for donators!

right-click-player-to-view-description
Set this to true to be able to see a player's description as shown in description-format.
Note that NPCs are immune to being right-clicked on to prevent errors.

must-crouch-to-view-description
If right-click-player-to-view-description is enabled, then setting this to true means a player must crouch (aka SHIFT) while right-clicking to view a player's description.

description-format
This is the format used in the chat when using /character check, or when right-clicking a player!
Each line in this list is a line of text in chat.
Regardless of the line, {player} gets replaced with the player's username, and {orpdesc_(field)} gets replaced with the respective field (e.g. {orpdesc_name} is replaced with the player's character name)!
The description format also supports PlaceholderAPI and MVdWPlaceholderAPI, which essentially means you can use values from any plugin that supports them!

Is there a way to change the /character field changer?
Yes, there is! Everything regarding it can be changed from Descriptions' messages.
In there, find this configuration section:

field-manipulation:
   field-set-format:
   - ''
   - '&8[&6{field}&8]'
   - '{change}'
   - '&f{value}'
   change:
      single: '&a&l[CLICK TO CHANGE]'
      list: '&a&l// &7{value} '
      locked: '&c[LOCKED]'

Changing it as simple as changing the text or colours to make them match your server's style!

I want to have the player's character name be visible above their head, how would I do this?
To do this, we must install two plugins: TAB and PlaceholderAPI.
Let's first install TAB...
https://www.spigotmc.org/resources/tab-1-5-x-1-16-4.57806/
and then PlaceholderAPI...
https://www.spigotmc.org/resources/placeholderapi.6245/

Note: TAB will also automatically add other features like a custom tablist etc.
All of these features can be turned off from the TAB config, check the TAB wiki out:
https://github.com/NEZNAMY/TAB/wiki/config.yml

Now that we have all the plugins ready, we first want to use unlimited-prefix-suffix-mode to turn on armor stands in TAB (Bukkit only).
This will hide the original nametag, letting us change it to a custom one.
Find this line in your config.yml (might be also called bukkitconfig.yml) for TAB, and change it like so:

unlimited-nametag-prefix-suffix-mode:
  enabled: true

Now let's go ahead & change the customtagname format for every user, by changing it up in __OTHER__.

_OTHER_:
    tabprefix: "%vault-prefix%"
    tagprefix: "%vault-prefix%"
    tabsuffix: "%afk%"
    tagsuffix: "%afk%"
    customtabname: "%essentialsnick%"
    customtagname: "%orpdesc_name%"

Save this configuration, and then use /tab reload on your server! Congratulations, you should now have a player's name set to their character name!

Clone this wiki locally