VIPTimer Manual

VIPTimer is a timer used to time for possession of permissions, acting essentially as a timer of command execution. VIPTimer supports file synchronization across different servers (as long as they've connected to the same MySQL database), in order to keep the VIP type configuration consistent.

VIPTimer hasn't been optimized for fault tolerance, so it's a bad idea to make change to internal files, like tasks.yml.

Command Usage

Commands start with /viptimer, abbreviated as /vipt. Commands listed below can only be used by Operators.


CMD	Explanation
`/vipt give <playername> <type> <duration>`	Give a player a VIP of some type, as configured in types.yml. If the corresponding record exists, this command will do addition or subtraction based on the "until" field of the previous record. `duration` format can be seen in part "Format Convention"
`/vipt set <playername> <type> <until> [new?]`	Set the expiration date of a VIP of a player. `until`format can be seen in part "Format Convention". If the target player hasn't got the VIP, "new" should be added at the end of the command to indicate this command creats a new VIP record.
`/vipt take <playername> <type>`	Take a VIP from a player.
`/vipt transown <from> <from-type> <to>`	Transfer the ownership of the VIP of type "from-type" from "from (player)" to "to (player)". This makes no change to the expiration date.
`/vipt chtype <playername> <from> <to>`	Change the type of a VIP of a player, from "from (type)" to "to (type)". This makes no change to the expiration date.
`/vipt reload`	Reload the FileConfiguration objects in the memory.

Configuration

config.yml - Basic configuration

# Database settings
database:
  username: ""
  password: ""
  host: "localhost"
  port: 3306
  # Create on your own
  db: "viptimer"
# Can be either "distributor" or "receiver"
# Role will be "none" if not specified
# Details can be seen at https://wiki.oases.red/VIPTimer_Manual.
role: distributor
# A thank-you note that is shown when a VIP is given to or taken from a player.
# Nothing will be shown if not specified.
thank-you-text: ~

types.yml - Defines different types of VIPs. See below for detailed usage.

types:
    vip1:
        displayname: ~
        give:
            - lp user $playername permission set ... true
        take:
            - lp user $playername permission set ... false
inst_id: ~

tasks.yml - The internally plugin-operated file used to store delayed tasks or messages scheduled for players that aren't online at the time the give/take commands are executed. This mechanism makes it more stable to execute commands from different plugins, when targeted at players. The delayed commands will be executed once the target player is online (PlayerJoinEvent).

File Synchronization (Beta)

VIPTimer supports file synchronization, from one unique distributor to any random receiver.

Simply speaking, the mechanism overwrites receiver's files with distributor's file content at a fixed rate. types.yml is the synchronized file of this plugin.

Deployment

First we must determine a main server which is of the role "distributor". To make a server a distributor, just set the role to "distributor" in config.yml.

Server restart (not reload) is needed after the change of role.

On other servers (with VIPTimer installed) we set the role to "receiver", this makes it active to receive any file change coming from distributor.

Note: the communication (e.g. file change detection) among the servers is based on MySQL, thus requiring all of the plugins configured to connect the same database.

When there is no need for synchronization...

Just set the role to "~"(null) and restart the server.

Database Setup

Operational running of the plugin requires manual database setup. Just create the database of the name you want and create tables with the statements in https://github.com/oasis-mc/viptimer/blob/main/init.sql.

CREATE TABLE `records` (
	`id` INT unsigned NOT NULL AUTO_INCREMENT,
	`playername` VARCHAR(20) NOT NULL,
	`type` VARCHAR(10) NOT NULL,
	`until` BIGINT unsigned NOT NULL,
	`created_by` VARCHAR(20) NOT NULL,
	`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
	`updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
	PRIMARY KEY (`id`)
);

CREATE TABLE `distribution` (
    `id` INT unsigned NOT NULL AUTO_INCREMENT,
    `dist_by` VARCHAR(36) NOT NULL,
    `dist_content` TEXT NOT NULL,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
);

CREATE TABLE `receipt` (
    `id` INT unsigned NOT NULL AUTO_INCREMENT,
    `dist_by` VARCHAR(36) NOT NULL,
    `recv_by` VARCHAR(36) NOT NULL,
    `recv_count` INT unsigned DEFAULT 0,
    `recv_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
);

CREATE TABLE `delivery` (
    `id` INT unsigned NOT NULL AUTO_INCREMENT,
    `inst_id` VARCHAR(36) NOT NULL,
    `playername` VARCHAR(20) NOT NULL,
    `type` VARCHAR(10) NOT NULL,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
);

Try not to run the statements in root. If needed, you can create a new account for this plugin with the following statements.

CREATE USER viptimer IDENTIFIED BY password;
GRANT ALL PRIVILEGES ON <db-name>.*;
FLUSH PRIVILEGES;

Format Convention

`/vipt give ... <duration>`

"duration" must match the regex -?\d+[h|d|m], that is an ordinary integer (can be negative) followed with letter h, d or m.

h - hours
d - days
m - months, not minutes

Minute precision can be reached by set command.

/vipt give Constant137 oasis_life 20d - Give player Constant137 the VIP of type "oasis_life" of which expiration date is exactly 20 days(1.278e9 ms) after the command execution.
/vipt give Constant137 oasis_life -20d - Shorten the expiration date of the existing record by 20 days. This (with negative number included) can only succeed when the target record exists.

`/vipt set ... <until> [new?]`

"until" can be of two format. The first is Unix Timestamp, and the second is a standardized date string accurate to seconds. If the record is not present (creating a new record with this command), "new" should be added at the end.

For Unix Timestamp, any integer is theorectically allowed, but there is no guarantee for the precision.
The date is standardized with yyyy-MM-dd_HH:mm:ss. E.g. 2023-08-31_19:00:32. Underscore should not be omitted.

/vipt set Constant137 oasis_life 2023-08-31_21:30:00 - Set the expiration date of Constant137's "Oasis Life" to 2023-08-31_21:30:00.
/vipt set Subilan oasis_new 2023-09-21_23:59:59 new - Give player Constant137 the VIP of type "oasis_new" of which expiration date is exactly 2023-09-21_23:59:59.

VIP Definitions

Important: VIP configuration and definition are only needed on distributor servers. The file types.yml on any receiver server will be directly overwritten with the content from distributor. No edition record will be left.

types:
    oasis_life: # <-- [1]
        displayname: Oasis Life # <-- [2]
        give:
            - lp user $playername parent add oasislife
        take:
            - lp user $playername parent remove oasislife

`displayname`

As above: [1] is called the internal name of the VIP, which is used internally and displayed to Operators. [2] is the display name of the VIP which is displayed to Players.

As a key, internal name should be legal to be a key of a YAML file.

Display name can be decorated using the MiniMessage syntax. Of course you can just add some simple text.

`give` and `take`

"give" and "take" hold the commands that are executed when the VIP is given to or taken from players. It is strongly advised to involve commands that have opposite effects in both fields, and make the number of the commands the same.

Placeholders

Placeholders are supported in give or take commands.

$playername - Target player's name.
$displayname - The displayname of the VIP. Fallback value: internal name.
$raw_displayname - The raw text of displayname, without any additional color or decorations.