search

itsmeow / ClaimIt

A mod for claiming land in Forge 1.12
GNU Lesser General Public License v3.0
3 stars 2 forks source link
hacktoberfest

readme

ClaimIt

Documentation Status

A mod for claiming land in Forge 1.12

Why is this mod special?

This mod is built with the idea of creating easy compatibility that allows mods to integrate properly with the claiming system to avoid the need for banning items. It also includes an in-depth but configurable permission system to allow full control over who can do what, and what is allowed where, as well as in-depth administration tools.

Do my users need to download ClaimIt?

No. It's server side only, but loads on integrated servers (singleplayer/LAN) just fine.

I have questions/need support! Where can I get help?

The best places to get help are the ingame help command, this article, and my Discord server.

API

ClaimIt has an expansive API for integration and addition. You can view its documentation via clicking the docs badge or looking at the docs/ directory.

Using the base mod

ClaimIt is the base mod, which the API is completely independent of. ClaimIt handles protections and hooks/commands.
ClaimIt includes an expansive ingame help command, accessed with /claimit help. You can also view all of the sections below for a general outline of commands, permissions, features, and configuration.

Right click two corners with the claiming item to create a claim! The default item is shears.

Member Permissions

Member permissions are a subclass of permission that can be assigned to a player in a group or claim. Different member permissions grant different permissions and abilities. You can give players these permissions with /claimit claim permission <add/remove> <permission> <player>. It also supports wildcards (*) and multiple arguments. Example: /ci claim permission add modify,use Player23,Player43 or /ci claim permission remove * *

Toggle Permissions

Toggle permissions are a subclass of permission that can be enabled or disabled per claim, and are stored per claim. They can control certain global protections for claims, such as explosions. They can be modified with /claimit claim toggle [toggle name]. To change values or force claims to values see the API Configuration 1 section below.

Member Toggle Permissions

There can also be toggle perms sharing names with member perms. Toggling these "member toggles" to ON makes that member permission publicly available. E.g. toggling the modify toggle will allow anyone to place and break blocks in that claim. Not all member permissions have a toggle.

Commands

ClaimIt includes an abundance of commands both for player use and admin use.

Base Commands

Claim Commands

Subclaim Commands

Group Commands

Help Commands

Claim Blocks

Permissions

ClaimIt has basic Sponge/Spigot integration (yes, LuckPerms included!)
With Sponge present, most of the default command permissions are allowed by default.

You will need to give users access to claimit.claim.create and claimit.subclaim.create when using Sponge!

List of non default non admin permissions (Sponge only):

List of default permissions:

The list of non default admin permissions:

The list of default admin permissions (these require one of the above, but are default. You can set these to false to block a specific one):

I'll say it again.
You will need to give users access to claimit.claim.create and claimit.subclaim.create when using Sponge!

Administration

ClaimIt provides an abundance of administration tools, namely the ability to bypass protections and modify claim toggles, members, etc. Read the admin permissions above for a general idea of what you'll need. In order to use ANY admin features you will need admin enabled. To do so, run /claimit admin. So long as this is enabled and you have claimit.claim.manage.others, you can bypass protections. Setting block limits is very easy, and can be done via the /claimit claimblocks (setallowed/addallowed) (player) (amount) command, so long as you have permission.

Configuration

ClaimIt provides many configurable features. Currently, there are three configs, all of which are in the config folder.

API Configuration 1 (claimit_api.cfg)

This configuration allows forcing values to toggles in all claims and also changing the default values for toggles. This means you can for example force pickup_item to allowed (true) in all claims. Here's an example configuration for that:

claim_permissions {
    pickup_item {
        # Set true to force pickup_item in claims to the value of 'force_pickup_item_value' [default: false]
        B:do_force_pickup_item_value=true

        # Set to whatever value you want this to be if 'do_force_pickup_item_value' is true [default: true]
        B:force_pickup_item_value=true
    }
}

Setting do_force_toggle_name_value to true will ensure that all claims have toggle_name set to whatever the value of force_toggle_name_value is.

Here's a similar example limited to simply setting the default for pickup items from ON to OFF:

claim_permissions {
    pickup_item {
        # Sets the default value for this toggle in new claims and under the help information for this toggle. [default: true]
        B:default_value=false
    }

API Configuration 2 (claimitapi-2.cfg)

Currently this configuration contains only one value.

general {
    # Enable or disable the entire subclaim system
    B:enable_subclaims=true
}

Setting enable_subclaims to false will remove any existing subclaims and destroy the data, and prevent creation and interaction with subclaims, including /claimit subclaim and any subcommands.

ClaimIt Configuration (claimit.cfg)

This is the most useful configuration for most users. This allows setting a variety of values.

general {
    # The amount of claim blocks to be rewarded to players every "claim_blocks_accrual_period" ticks
    I:claim_blocks_accrual_amount=0

    # The period, in ticks (1/20 of a second), at which "claim_blocks_accrual_amount" rewards will be seperated by. 0 to disable.
    # Min: 0
    # Max: 2147483647
    I:claim_blocks_accrual_period=0

    # Put here the item ID that you wish to use for claiming.
    S:claim_create_item=minecraft:shears

    # Should match the display name of the claiming item, this is what is shown to users in the base command menu.
    S:claim_create_item_display=Shears

    # The text shown in the action bar upon entering a claim. Supports & color/formatting codes. Use %1 for owner name/uuid and %2 for claim name.
    S:claim_entry_message=&dEntering: &c%2&d - owned by: &e%1

    # The text shown in the action bar upon exiting a claim. Supports & color/formatting codes. Use %1 for owner name/uuid and %2 for claim name.
    S:claim_exit_message=&6Exiting: &c%2&6 - owned by: &e%1

    # The default maximum area a claim can be for non-admins, in square blocks. Default 40,000 sq blocks = 200 blocks x 200 blocks. This can be increased and decreased via the claimblocks command.
    # Min: 4
    # Max: 2147483647
    I:default_claim_max_area=40000

    # Disables the ability to have any PVP in claims.
    B:forceNoPVPInClaim=false

    # Sets the maximum time borders can be shown with /claimit showborders. Please note each second is around 12 to 30 packets from the server to each player in order to show borders, therefore it is limited.
    # Min: 1
    # Max: 2147483647
    I:max_show_borders_seconds=30

    # Maximum length a tag can be. Must be greater than or equal to minimum.
    # Min: 1
    # Max: 30
    I:max_tag_length=4

    # Minimum length a tag can be. Must be less than or equal to maximum.
    # Min: 1
    # Max: 30
    I:min_tag_length=3

    # Deletes chunks that do not have claims present when enabled. After all region data has been pruned, this option does nothing until the server is restarted. DO NOT USE THIS WITHOUT BACKUPS OR AN UNDERSTANDING OF WHAT YOU ARE DOING. THIS WILL DELETE ANYTHING THAT IS NOT WITHIN A CHUNK THAT HAS A CLAIM AND RETURN IT TO THE DEFAULT GENERATION. I AM NOT RESPONSIBLE FOR ANY LOSS OF DATA. DO NOT ASK ME IF YOU CAN UNDO THIS, YOU CANNOT.
    B:prune_unclaimed_chunks=false

    # Sets the cooldown in seconds between each use of show borders
    # Min: 0
    # Max: 2147483647
    I:show_borders_cooldown=60

    # The text placed before the tag in chat. Supports & color/formatting codes.
    S:tag_prefix=&a[

    # The text placed after the tag in chat. Supports & color/formatting codes.
    S:tag_suffix=&a] 
}

claim_blocks_accrual_amount represents the amount of claimblocks that will be accrued per claim_blocks_accrual_period, given that both is greater than 0.
claim_blocks_accrual_period is a number represented in ticks (1/20 of a second) in which claimblocks will be rewarded, based on the time in which the user joined, meaning the exact award time is different for each player.
claim_create_item is the item ID that will be used for creating claims and subclaims. By default it is minecraft:shears, but it can be any valid item.
claim_create_display is a piece of text that will be displayed as the claiming item when a user runs /claimit. It does not necessarily have to match the actual item name, but it generally should so your users know what to do.
claim_entry_message is the text shown in the action bar upon entering a claim. Supports & color/formatting codes. Use %1 for owner name/uuid and %2 for claim name.
claim_exit_message is the text shown in the action bar upon exiting a claim. Supports & color/formatting codes. Use %1 for owner name/uuid and %2 for claim name.
default_max_claim_area is the amount of claimblocks in which users will start with.
forceNoPVPInClaim is a boolean that when set to true will make all claims block PVP, regardless of any settings or memberships.
max_show_borders_seconds is a number, in seconds, representing the length of time which /claimit showborders will display borders for. This is set at 30 for network performance reasons (each claim is ~12 to 30 packets per second).
max_tag_length is the maximum length of a group's tag (excluding formatting codes)
min_tag_length is the minimum length of a group's tag (excluding formatting codes)
prune_unclaimed_chunks is a boolean that when enabled will regenerate (remove constructions/modifications) of any chunks that do not contain a claim. This is a HIGHLY destructive operation that fires exactly once after the server starts with this enabled. After completion, it should promptly be set back to false. I am NOT responsible for data loss from this option. Do not take this one lightly.
show_borders_cooldown is a number, in seconds, representing how long you must wait between using /ci showborders. Keep in mind the shorter this is the more network performance problems you may have.
tag_prefix is the text put before a tag in the chat. Supports color and formatting codes with &
tag_suffix is the text put after a tag in the chat. Supports color and formatting codes with &