5.0.0 alpha

Thanks for helping try out PVX 5.0!

Concepts

Vaults

Vaults are single inventories that a player can own and access. A vault can be up to six rows tall.

Server admins can define the usable space of vaults, and can set up next/previous buttons in them.

Vaults can be granted directly by server admins, or can be granted as a part of a bundle.

Bundles

A bundle is a collection of vaults that are unlocked for a user all at once.

They are gated behind some quantity of requirements (or are granted to all users): * Command-based: A bundle may be unlocked purely with a command. * Permission node requirement: A player might need a particular permission node to unlock a bundle. * This requirement can, optionally, persist for continued access to the unlocked vaults. * Purchase cost: A bundle may cost in-game currency to unlock.

A server admin can set a bundle to have any combination of the above requirements.

Once unlocked, vaults are either auto-created or require activation in the /pv menu. The activation requirement exists so that admins can allow players to choose how many vaults they actually have, or when certain ones are added to their list. This can also be skipped, so activation never is an issue.

It is possible to set things up so that users don't even ever see the concept of a bundle, auto-unlocking vaults as they hit permission node or command requirements. Or, bundles can be skipped entirely and access to vaults can be done purely with a command granting an extra vault to a player. Infinite flexibility!

Commands

User Commands

/pv

Open up the menu. Lists all the vaults you have access to, with next/prev buttons in the bottom corners as necessary. If there are bundles you can unlock or purchase, those can be found with a button at the bottom. If there are vaults you unlocked from a bundle but the vaults require activation, these too can be found with a button at the bottom.

Permission: pvx.vault.command

/pv <vault name or id>

Opens up a specific vault by name or ID.

Permission: pvx.vault.command

/pvnickname <vault name or id> [nickname]

Sets (or unsets) a vault's nickname.

Permission: pvx.vault.nickname

Admin Commands

Permissions

Access to all admin commands requires the pvx.admin permission node. This node also grants all of the other nodes as children. You may selectively revoke nodes from admins to limit access.

Accessing player vaults

/pvadmin load <player> <vault>

Loads a particular player's vault by name or id.

Permission: pvx.admin.load

Adding New

/pvadmin add <vault type name> [number of rows (1-6)]

Creates a vault type. The icon will match the item in your hand, or will default to a regular chest. Number of rows will default to 6. Running this command will pop up an inventory with a default next and previous button. Move these, if you wish, or drop them to remove the buttons entirely. Add items to add blockers to the vault, to establish slots that are not possible to use.

Permission: pvx.admin.add.vaulttype

/pvadmin add <bundle short name> [decorated name]

Starts the process of creating a bundle. Use the /pvadmin bundle commands to complete the process. Decorated name can be MiniMessage-formatted. If not included, the decorated name will just be the short name.

Permission: pvx.admin.add.bundle

Bundle Creation

All commands here require first running the above add bundle command, and only work for non-finalized bundles.

Unfinished bundles are lost on server restart.

/pvadmin bundle <bundle short name> package <vault type> [flags]

Adds a package, a quantity of same-property vaults, to the bundle. Without flags, adds one of the chosen type.

Flags:

--name <name>
- Sets a name for the vaults which will apply to all in the package (best done with a quantity of 1).
--quantity <number>
- Sets a quantity of vaults of the chosen type to grant. Defaults to 1, if no flag.
--createOnGrant <true/false>
- Sets if the vault is created automatically when the bundle is acquired by a player. Defaults to true.

Permission: pvx.admin.add.bundle

/pvadmin bundle <bundle short name> cost <amount>

Sets a cost for the bundle. Defaults to 0 cost (free) if not set by this command.

Permission: pvx.admin.add.bundle

/pvadmin bundle <bundle short name> limitation command>

Marks the bundle as requiring an admin to run the /pvadmin unlock command for a player before they can potentially unlock it.

Permission: pvx.admin.add.bundle

/pvadmin bundle <bundle short name> limitation permission <permission node> [--persists]

Sets a permission node requirement to unlock the bundle.

With the --persists flag, this requirement continues after unlocking, meaning a player could lose access to the vaults unlocked with this bundle.

Permission: pvx.admin.add.bundle

/pvadmin bundle <bundle short name> finalize [flags]

Finalizes creating this bundle. It now can be used in other commands.

Optionally, flags (active, obtainable, usable) may be modified here from defaults. See the flags command below for details.

Warning

Newly created bundles have the flags "active" and "usable" but not "obtainable"

In order for a player to unlock the new bundle, you must set the obtainable flag. This is done to ensure admins can review newly created bundles before pushing them live, can add permission nodes as appropriate, or even run the grant command in advance to deploy all at once.

Permission: pvx.admin.add.bundle

Flags

/pvadmin flags bundle <bundle short name> [flags]

Views and, optionally, sets a bundle's flags.

Flags:

--active <true/false>
- Sets if the bundle shows up in the unlock command.
--obtainable <true/false>
- Sets if players can get new bundles of this type, such as by purchase or permission unlock.
--usable <true/false>
- Set to false, even previously granted vaults from this bundle are inaccessible to players.
--cost <amount>
- Updates the bundle's cost. Setting to 0 may instantly grant it to players, based on other limitations.

Permission: pvx.admin.flags.bundle

/pvadmin flags vaulttype <vault type> [flags]

Views and, optionally, sets a vault type's flags.

Flags:

--active <true/false>
- Sets if the vault type shows up in the grant command.
--usable <true/false>
- Set to false, even previously granted vaults of this type are inaccessible to players.

Permission: pvx.admin.flags.vaulttype

Granting a Vault

/pvadmin grant <player name> <vault type>

Grants a player a vault of the given type.

Permission: pvx.admin.grant

Unlocking a Bundle

/pvadmin unlock <player name> <bundle short name>

Unlocks a bundle with the "command" limitation. If the bundle is free and the player meets all permission node limitations, the bundle's vaults are instantly granted. If it has a cost and the player meets all permission node limitations, the bundle shows up in the purchase section of the /pv command.

Permission: pvx.admin.unlock

Example Setups

The Simple Perm Groups

Maybe you just want a few roles to get access to some extra vaults, and nobody needs to ever see the concept of a bundle.

Goals:

All vaults are full size, with previous and next buttons in the bottom corners to easily navigate.
All players have one vault
Players in the "cool" group have two extra vaults (3 total)
Players in the "mega cool" group (who get "cool" perks) have three extra vaults (6 total)

Commands to Run

Hold a chest in your hand.
- /pvadmin add vaulttype vault
- Immediately close this vault, as it starts with the defaults you want.
- This creates a vault type with 52 slots (2 taken by the prev/next buttons), creatively called "vault"
/pvadmin add bundle everyone
/pvadmin bundle everyone package vault
/pvadmin bundle everyone finalize --obtainable true
- This has created a bundle - called "everyone" - that all players get and contains one vault of type "vault"
/pvadmin add bundle cool
/pvadmin bundle cool package vault --quantity 2
/pvadmin bundle cool limitation permission myserver.cool
- This permission node should match the node that members of the "cool" group get. Or just create one and give it to them.
/pvadmin bundle cool finalize --obtainable true
- This has created a bundle with two vaults for members of the "cool" group.
/pvadmin add bundle megacool
/pvadmin bundle megacool package vault --quantity 3
/pvadmin bundle megacool limitation permission myserver.megacool
- As like before, the permission node here should be one that "megacool" group members get.
/pvadmin bundle megacool finalize --obtainable true
- Finally, a bundle only accessible to the "megacool" group with three vaults has been created.

The vault shop

Maybe you want to sell some bundles.

Goals:

Create a bundle selling five vaults.

Commands to Run

Hold a chest in your hand.
- /pvadmin add vaulttype vault
- Immediately close this vault, as it starts with the defaults you want.
- This creates a vault type with 52 slots (2 taken by the prev/next buttons), creatively called "vault"
/pvadmin add bundle forsale <rainbow>Awesome Vaults For Sale
/pvadmin bundle forsale package vault --quantity 5
/pvadmin bundle forsale cost 500
/pvadmin bundle forsale finalize

Repeat steps 2 - 5 with new bundle names for as many bundles as you want to sell.

Notes

Alpha Testing

This plugin is currently in limited alpha testing. Please help out in any way you can, but keep in mind the plugin may have bugs. Keep up to date, if running the alpha test yourself.

Update checking

The plugin will always check for updates, sending the following info for usage statistics:

Plugin version
Server name (e.g. Paper)
Server version