hGrant is a configurable grant system for Minecraft servers.
The plugin allows players or staff members with access to open a grant GUI for a target player and issue configured rewards, temporary groups, currency rewards or any other action-based grant.
Each grant can have its own GUI item, limit, cooldown, restore timer, duration, actions for the grantor, actions for the target and PlaceholderAPI values.
Main Features

• Grant GUI opened through /grant <player>.
• Separate GUI files for different grantor groups.
• Configurable grant limits.
• Configurable cooldown after each grant.
• Optional limit restore timer.
• Temporary duration values for grant actions.
• Amount values for currency-style grants.
• Separate item views for available, cooldown and exhausted states.
• Custom materials, names, lore, enchantments and item flags.
• Custom decorative GUI items.
• PlaceholderAPI placeholders for available grants, used grants and cooldowns.
• SQLite storage by default.
• Optional MySQL storage.
• Optional LuckPerms integration.
• Optional Vault actions.
• Public GrantEvent API.
• Hex color support.

How It Works
A player uses:
The plugin checks whether the sender can use the grant system, finds the correct GUI for the sender, loads available grants and opens the configured menu for the selected target.
When a grant item is clicked, hGrant checks its current state:

• available - the grant can be issued.
• cooldown - the player must wait before issuing this grant again.
• notAvailable - the grant limit has been reached.

If the grant is available, the plugin saves the updated usage data, executes grantor actions and then executes target actions if the target is online.
Group-Based GUI Selection
hGrant can use LuckPerms groups or permissions to decide which GUI a player should see.
Default GUI files are stored in:
Included GUI templates:
Each file can have its own menu title, size, grant items and decorative items.
Grant Limits
Each configured grant can have its own limits.
Supported grant settings:
cooldown controls how long the grantor must wait after issuing the grant.
uncooldown controls when used limits can be restored.
max controls how many times the grant can be used.
duration can be used in actions for temporary group grants.
amount can be used in actions for currency-style rewards.
GUI Item States
Each grant item can have three different visual states:

• available
• cooldown
• notAvailable

For every state you can configure:

• material
• display name
• lore
• enchantments
• item flags
• grantor actions
• target actions

This makes the GUI clear for the player and allows different behavior depending on the grant state.
Action System
hGrant uses configurable actions for messages, commands, sounds, visual effects and economy operations.
Common action examples:
Example grant action:
LuckPerms Integration
If LuckPerms support is enabled, hGrant can read the grantor's groups and use them to select the correct GUI and available grant rules.
The plugin can also use LuckPerms priorities to help prevent invalid grant order when granting permission groups.
Database Storage
hGrant stores grant usage data in a database.
Supported storage modes:

• SQLite
• MySQL

Stored data includes:

• player UUID
• grant ID
• used amount
• cooldown end time
• next restore time

SQLite is used by default. MySQL can be enabled in config.yml.
Configuration
Main configuration file:
GUI files:
Example group rule structure:
Example GUI item structure:
Commands
Opens the grant GUI for the selected online player.
Permissions
Allows access to the grant system.
Group-specific permissions can also be used:
These permissions can be used when LuckPerms group detection is not the only access method.
PlaceholderAPI
hGrant registers PlaceholderAPI placeholders with the identifier:
Available placeholder formats:
Examples:
These placeholders can be used in GUI lore, scoreboards, menus and other plugins with PlaceholderAPI support.
Internal Placeholders
Internal placeholders for actions and GUI text:
Developer API
hGrant can call a public GrantEvent after a grant is successfully issued.
The API can be enabled or disabled in the configuration:
Requirements

• Java 16 or newer.
• Minecraft 1.16 or newer.
• Spigot / Paper / compatible server core.
• PlaceholderAPI.

Optional:

• LuckPerms
• Vault
• MySQL

Important: PlaceholderAPI is required.
Installation

1. Install PlaceholderAPI.
2. Place hGrant.jar into the plugins folder.
3. Start or restart the server.
4. Open config.yml.
5. Configure grant groups, limits and database settings.
6. Configure GUI files in the guis folder.
7. Restart the server after editing the configuration.

Notes

• The command works with online target players.
• GUI files are selected based on group or permission access.
• Each grant can have separate visual states.
• Grant usage is saved in the database.
• LuckPerms and Vault are optional integrations.
• Actions make the system flexible for groups, rewards, messages and effects.