Claim Block Accruals

Claim Block Accruals

GPExpansion can manage GriefPrevention3D claim block accrual rates and limits by group, permission, and per-player override.

This feature is for servers that want default players, VIPs, donors, staff, or reward winners to accrue claim blocks differently without editing GriefPrevention3D internals.

What It Controls

Each accrual profile controls three values:

Setting	Meaning
blocks-per-hour	How many claim blocks the player accrues per hour
max-blocks	Maximum accrued claim blocks the player can hold
max-claims	Maximum number of top-level claims the player can create

max-claims: 0 disables the claim count cap for that profile.

Subclaims are not counted against max-claims; only top-level claims are capped.

Configuration

The feature is configured in plugins/GPExpansion/config.yml:

accruals:
  # Amount of accrued claim blocks per hour and max cap, based on permissions.
  # You can add/remove as many names here that you want.
  # Permission nodes are in the format griefprevention.accruals.<groupname>.<type>
  groups:
  - name: default
    blocks-per-hour: 100
    max-blocks: 80000
    max-claims: 0 # disabled
  - name: vip
    blocks-per-hour: 20
    max-blocks: 250000
    max-claims: 10
  - name: elite
    blocks-per-hour: 50
    max-blocks: 1000000
    max-claims: 20
    permission: elite-reward

The name is the accrual profile name. It is also used for group matching and permission matching.

The optional permission value creates an extra one-off permission match. In the example above, elite can match either the elite group/profile permission or the extra griefprevention.accruals.elite-reward permission.

Profile Matching

GPExpansion starts with the default profile, then checks the other configured profiles in list order. If more than one profile matches, the later matching profile wins.

A profile can match in any of these ways:

Match Type	Example
Vault/LuckPerms group name	Player is in group vip and config has name: vip
Base profile permission	griefprevention.accruals.vip
Optional reward permission	griefprevention.accruals.elite-reward when permission: elite-reward is configured

The base profile permission applies the whole profile. For example, griefprevention.accruals.elite gives that player the elite blocks-per-hour, max-blocks, and max-claims values.

Permission Nodes

Use these permission formats:

griefprevention.accruals.<group>
griefprevention.accruals.<group>.blocks
griefprevention.accruals.<group>.max
griefprevention.accruals.<group>.claims
griefprevention.accruals.<permission>

The base node, such as griefprevention.accruals.vip, selects the whole profile.

The typed nodes are documented for permission managers and future fine-grained display, but the current profile resolver uses the whole-profile node, optional permission: node, and Vault/LuckPerms group membership.

Player Overrides

Player overrides are written only when an admin sets them with /gpx accruals player.

Overrides take precedence over the matched group profile. They can override one value or all values:

/gpx accruals player Steve set per-hour 30
/gpx accruals player Steve set max-blocks 250000
/gpx accruals player Steve set max-claims 10
/gpx accruals player Steve reset all

If Steve is in vip, but an admin sets per-hour to 30, Steve keeps the VIP max block and max claim values while using the custom 30 blocks/hour override.

Admin Commands

All /gpx accruals commands require GPExpansion admin access.

Check A Player

/gpx accruals check [player]

Shows the player's effective profile, source, blocks/hour, max blocks, max claims, and any player override.

Console must provide a player name:

/gpx accruals check Steve

Edit A Group

/gpx accruals group <group> set|add|remove <per-hour|max-blocks|max-claims|all> <amount>

Examples:

/gpx accruals group vip set per-hour 20
/gpx accruals group vip add max-blocks 50000
/gpx accruals group vip remove max-claims 2
/gpx accruals group vip set all 0

remove subtracts from the current value and will not drop the value below 0.

Edit A Player Override

/gpx accruals player <name> set|add|remove|reset <per-hour|max-blocks|max-claims|all> [amount]

Examples:

/gpx accruals player Steve set per-hour 30
/gpx accruals player Steve add max-blocks 100000
/gpx accruals player Steve remove max-claims 1
/gpx accruals player Steve reset all

Create A Group

/gpx accruals creategroup <name> [blocks-per-hour] [max-blocks] [max-claims] [permission]

Examples:

/gpx accruals creategroup vip 20 250000 10
/gpx accruals creategroup elite 50 * 20
/gpx accruals creategroup event 0 500000 5 event-reward

When LuckPerms has a group with the same name, GPExpansion sorts weighted groups with lower weights higher in the accruals.groups list.

Use * for a numeric value to inherit the highest value from LuckPerms-weighted groups below the new group. For example, if vip is lower than elite, this command inherits vip's max-blocks:

/gpx accruals creategroup elite 50 * 20

The optional [permission] argument creates an extra permission match. Leave it out when the group name itself is enough.

Delete A Group

/gpx accruals deletegroup <name>

This removes the group from accruals.groups and reloads GPExpansion internally.

LuckPerms And Vault Notes

Vault is used for group membership checks when available.

LuckPerms is used directly for group existence and weight checks when available. This allows /gpx accruals creategroup to place weighted groups in a predictable order.

If an accrual group does not match a Vault group, does not match a LuckPerms group, and has no permission: value, GPExpansion logs a warning because that config entry cannot match anyone except players given the base griefprevention.accruals.<group> permission.

Config Migration

GPExpansion automatically checks for a missing or broken accruals.groups section during config migration.

If accruals.groups is missing, the default section is inserted into config.yml. If a valid accruals.groups section already exists, it is left untouched so custom server profiles are preserved.