Limits

A common requirement of server admins is that they want to limit the number of regions that a player can own at a time. Region-limits can be configured within the config.yml at the Limits-section.
Before reading this article it is highly recommended to read the article about RegionKinds and RegionKindGroups: https://github.com/alex9849/advanced-region-market/wiki/Regionkinds-&-RegionkindGroups

The following configuration snippet contains 3 limit-groups named examplegroup1, examplegroup2 and examplegroup3:

Limits:
  examplegroup1:
    total: 1
    regionkinds:
      Default: -1
      starter: 1
      small: 3
      medium: 5
      large: 0
      shop: 1
    regionkindgroups:
      citybuild-plot: 4
  examplegroup2:
    total: 10
    regionkinds:
      Default: -1
      starter: 1
      small: 2
      medium: 1
      large: 1
      shop: 1
    regionkindgroups: {}
  examplegroup3:
    total: -1
    regionkinds:
      Default: -1
      starter: 1
      small: 2
      medium: 2
      large: 2
      shop: 2
    regionkindgroups: {}

You can add or remove limit-groups by deleting or adding new configuration blocks like in the scheme above.

Limit-groups need to be assigned to players. This is being done by adding certain permissions to them.
These permissions have the following syntax: arm.limit.<limitgroupName>.
For example, if we would want to assign the limit-groups examplegroup1 and examplegroup2 to a player, we would add the permissions arm.limit.examplegroup1 and arm.limit.examplegroup2 to them.

A limit-group contains a global limit named total. The value in total specifies the total number of regions that a player is allowed to own. In the context of limits -1 corresponds to infinity. Which means that the limit for that category gets removed for players that belong to that group. The opposite of that is 0, which would block the player from owning any regions at all.

The section below is the regionkinds-section. It contains limits for regionkinds. The semantics of them is the same as for the total-field. If a regionkind has not been added to a limit-group, the plugin will treat the limit for that regionkind as unlimited.

The same counts for regionkindgroups.

If a player got assigned to multiple limit-groups, all limit groups that he is part of get merged into a single limit-group. This limit-group always consists of the best possible limits of all limit-groups that the player is a member of. It was mentioned that the limit for a Regionkind or RegionkindGroup is set to unlimited, if it is not defined in a limit group. This is not the case when merging multiple limitgroups. In that case the missing Regionkind is actually being reated as non existent. This means that if two limitgroup get merged where one group contains a limit for a regionkind and the other group doesn't, the value of the group that actually defined a limit gets picked.

---

Example:

Imagine the following scenario from the RegionKind article: There is a server with many regions. Some of them are user-shops. User-shops can be large or small. Others are city-plots for the players to build on. These city-plots are further separated into starter-plots, regular-plots, skyscraper-plots and vip-plots. The following configuration would make sense:

Create the Regionkinds: small-shop, large-shop, starter, regular, skyscraper and vip.
Add the RegionkindGroups: shop, city-plot.
Now add the Regionkinds small-shop and large-shop to the RegionkindGroup shop and add the Regionkinds starter, regular and skyscraper to the RegionkindGroup city-plot.

On our server we have also 3 groups. A member-group, a veteran-group and a vip-group. We configure our permissions plugin to do the following:

• The veteran-group inherits all permissions that the member-group got. The vip-group adds permissions to a player.
• A member that is part of the vip-group is also always part if the member-group or the veteran-group.

We want the following limits:

• Members
  • Can have 1 starter plot. (But not more)
  • Can have 2 plots of the regionkindGroup shop
    • This means that they should be able to spread that limit on the regionkinds small-shop and large-shop
  • Can have 3 plots of the regionkindGroup city-plot
    • This means that they should be able to spread that limit on the regionkinds starter, regular and skyscraper. (But because of the starter-limit they can still only own one starter-plot)
• Veterans
  • Can have everything that members can do. (Which includes the limit on the starter-plot and shop-plots)
  • Can have 5 plots of the regionkindGroup city-plot
• V.I.P.s
  • Can have everything that their other group can have
  • Can have 2 vip-plots

we could realize this behavior using the following configuration which contains the 3 limit-groups member, veteran and vip:

Limits:
  member:
    total: -1
    regionkinds:
      starter: 1
      vip: 0
    regionkindgroups:
      city-plot: 3
      shop: 2
  veteran:
    total: -1
    regionkinds: {}
    regionkindgroups:
      city-plot: 5
  vip:
    total: -1
    regionkinds:
      vip: 2
    regionkindgroups: {}

We add the permission arm.limit.member to our member-group.
arm.limit.veteran gets added to the veteran-group and arm.limit.vip gets added to the vip-group.

Now we can have the following cases:

• A player is part of member:
  • The only limit-group that the player has permissions for is the member-group. Therefore, only these limits get applied to him. These are:
    • The total limit is still unlimited, the group specified -1 as the total limit.
    • The starter-regionkind limit is set to 1.
    • The vip-regionkind limit is set to 0.
    • The city-plot-regionkindgroup limit is set to 3.
    • The shop-regionkindgroup limit is set to 2.
• A player is part of veteran:
  • Since we configured our permissions plugin such that veteran inherits all permissions from member, the player is now assigned to the limit-groups member and veteran. Therefore both get merged together.
    • The total limit is still unlimited, because both groups have -1 specified for the total limit.
    • The starter-regionkind limit is 1, because the member-limit defined that limit, and the verteran-limit didn't specify it.
    • The vip-regionkind limit is 0, because the member-limit defined that limit, and the verteran-limit didn't specify it.
    • The city-plot-regionkindgroup limit got raised to 5, because the veteran-limit specified the limit for that regionkindgroup as 5, which is higher than the limit that the member-limit specified (3).
    • The shop-regionkindgroup limit is 2, because the member-limit defined that limit, and the verteran-limit didn't specify it.
• A player is part of vip and member:
  • The player is now assigned to the limit-groups member and vip. Therefore both get merged together.
    • The total limit is still unlimited, because both groups have -1 specified for the total limit.
    • The starter-regionkind limit is 1, because the member-limit defined that limit, and the vip-limit didn't specify it.
    • The vip-regionkind limit got raised to 2, because the vip-limit specified the limit for that regionkindgroup as 2, which is higher than the limit that the member-limit specified (0).
    • The city-plot-regionkindgroup limit is 3, because the member-limit defined that limit, and the vip-limit didn't specify it.
    • The shop-regionkindgroup limit is 2, because the member-limit defined that limit, and the vip-limit didn't specify it.
• A player is part of vip and veteran:
  • The player is now assigned to the limit-groups member, veteran and vip. Therefore all three need to merged together.
    • The total limit is still unlimited, because all groups have -1 specified for the total limit.
    • The starter-regionkind limit is 1, because the member-limit defined that limit, and all other limit-groups didn't specify it.
    • The vip-regionkind limit got raised to 2, because the vip-limit specified the limit for that regionkindgroup as 2, which is higher than the limit that the member-limit specified (0). The veteran group didn't specify a limit for that regionkind so that group gets ignored for this regionkind.
    • The city-plot-regionkindgroup limit got raised to 5, because the veteran-limit specified the limit for that regionkindgroup as 5, which is higher than the limit that the member-limit specified (3). The vip-limt-group didn't specify a limit for that regionkindgroup so it gets ignored for this regionkindgroup.
    • The shop-regionkindgroup limit is 2, because the member-limit defined that limit, and all other limit-groups didn't specify it.