Skip to content

3.2 Requirements

Yanbing Zhao edited this page Jun 20, 2019 · 1 revision

The value of this option should describe the requirement of the player. If the player does not match the requirements, the corresponding item will not be shown. If a list is provided to describe a slot, it will try the next item. If none of them matches, the slot will be empty.

For example, if it is hoped that a wheat item should be shown to the player if the player has enough money (not less than 10), otherwise a barrier should be shown, the configuration could be like this:

Slot0 = [{
  Item {
    Count = 1
    ItemType = "minecraft:wheat"
    UnsafeDamage = 0
  }
  Requirements = "%economy_balance% >= 10"
}, {
  Item {
    Count = 1
    ItemType = "minecraft:barrier"
    UnsafeDamage = 0
  }
}]

If the player has enough money, the first item will be shown, otherwise the second one does.

JavaScript

The requirement string is JavaScript, which means that it will be compiled or interpreted to decide if the player matches the requirements. Any of the following return values of the script will be considered that the player matches the requirements:

  • The boolean true
  • The case insensitive string true, True, TRUE, etc.

In other cases, it will be regarded as false, which means that the player does not match the requirement.

If PlaceholderAPI String (%xxxx_xxxx_xxxx%) is appeared in the script string, it will be translated to a function call (papi('xxxx_xxxx_xxxx')), then calculated to get the result value.

If you has ever used some other menu plugins which uses JavaScript such as DeluxeMenus, the difference between them and VirtualChest needs to be noticed. For example, if you want to check if the player is Notch when configuring DeluxeMenus, you may write '%player_name%' == 'Notch', and it will be translated to 'Notch' == 'Notch', 'Dinnerbone' == 'Notch', or something else. However, if you are using VirtualChest, it will be translated to 'papi('player_name')' == 'Notch', which will produce a syntax error.

In VirtualChest, you should write %player_name% == 'Notch', and the string with placeholders will be translated to papi('player_name') == 'Notch', then calculated to 'Notch' == 'Notch', 'Dinnerbone' == 'Notch', etc. which have the correct JavaScript syntax.

Let's go back and talk about the requirement given at the beginning, %economy_balance% >= 10. If the player has 20, if will be equivalent to '20' > 10, and then JavaScript provides an implicit conversion from Number to String, so '20' > 10 is equivalent to 20 > 10, which is true.

There are some preset variables for convenience:

  • server, the Sponge Server object
  • player, the player object
  • papi, the function translating placeholders to its actual values
  • tick, ticks from opening the inventory, which can be used to create animations

Frequently used requirement string patterns

  • %player_name% == 'Notch'

    checks if the player is Notch

  • %economy_balance% >= 10

    checks if the player has got 10 (default currency)

  • player.hasPermission('virtualchest.open.self') or %player_perm_virtualchest.open.self%

    checks if the player has virtualchest.open.self permission, the first one is recommended

  • %server_online% > 20 or server.getOnlinePlayers().size() > 20

    checks if the count of online players is greater than 20, the first one is recommended

Of course, you can use && (and) or || (or) to combine scripts together. For example, %player_name% == 'Notch' && %economy_balance% >= 10 checks if the player is Notch and the player has got 10 (default currency).