Nexal Regions

A region land system for Minecraft servers: admins define regions with a selection wand, and players buy, sell and rent them with Vault money, with holograms, a listings GUI, member management, protection flags and optional taxes.

Features

Core Features

Region Definition - Admins define regions with an in-game selection tool (/region admin create); overlapping regions are refused
Buy/Sell System - Players buy regions for sale with Vault money; the seller is paid and told
Rent System - Hourly, daily (real time) or Minecraft-day rental periods, with lengths set in config
Member Management - Owners and renters add players who can build in the region; a renter's members lose access when the rental ends, and renters cannot remove the owner's members
Region Holograms - Floating region info; clicking it opens the region's screen
Admin GUI - /region admin opens a hub: settings screen, region list, statistics, pending offers, reload, export and import
Owner Management GUI - Owners configure their region via /region manage or a hologram click
Listings GUI - Browse regions for sale or rent, filter, sort and search them, teleport to one, or open its details to buy or rent it
Price Lock Protection - An upfront rent price is locked while the renter confirms; a GUI purchase is refused if the price changed since it was shown
Region Teleport Spawn Points - Owners, renters and members teleport to a region's spawn from anywhere

Region Protection

Build Protection - Non-members cannot break or place blocks, use buckets, edit signs, open containers and doors, use workstations and other usable blocks, trample crops, or break or use item frames, paintings, armor stands, animals and vehicles. Water, lava and pistons cannot move anything across a region border
Region Flags - Per-region toggles for PvP, hostile mob spawning, explosions and fire spread
Border Visualization - Players show region borders as particles or as a glowing outline only they can see
Entry Notifications - Owners and renters are told when someone enters their region

Rent Features

Auto-Renewal - The next period is paid from the renter's balance when due
Upfront Payment - Pay days in advance, prorated to the time added and capped at 7 days (configurable)
Eviction System - Reminders before rent is due, then warnings during a grace period before eviction
Stop Renting - Owners end a rental when the time already paid runs out, and can take it back
Deposited Rent - Optional mode where rent accumulates for the owner to claim; unclaimed rent is paid to the owner if the region changes hands

Ownership Features

Region Transfer - Give a region to another online player
Owner Name Hiding - Hide the owner from region info, listings, the region screen and holograms
Optional Taxes - A server tax per period on player-owned regions, per region or by default; unpaid regions return to the server
Region Limits - Max regions per player, set by permission
Purchase Offers - Admins offer a region to one player at a set price for a limited time; the player accepts or declines it from anywhere, and the owner is paid. Offers end when the region changes hands

Technologies

Spigot/Paper API 1.20.1+ - Minecraft server API
Utilizer - Configuration, messages, items, tasks, GUIs, holograms
ACF - Command framework
nexal-core - JSON and SQL persistence (MariaDB/MySQL), help menus, selection tool
Vault - Economy
PlaceholderAPI - Placeholder integration (optional)
DecentHolograms / HolographicDisplays / FancyHolograms - Used for holograms when installed (optional; native holograms otherwise)

Commands

Player Commands

Command	Description	Permission
`/region help`	Show help menu	`nexalregions.use`
`/region info`	View info about the region you're in	`nexalregions.use`
`/region manage`	Open the management GUI of the region you're in	`nexalregions.use`
`/region buy`	Buy the region you're in	`nexalregions.buy`
`/region rent [hour\|day\|mcday]`	Start renting the region you're in (default: day)	`nexalregions.rent`
`/region pay [days]`	Pay rent days upfront; run it again to confirm the locked price	`nexalregions.rent`
`/region leave`	Stop renting the region you're in	`nexalregions.use`
`/region add \<player>`	Add a member to your region (a renter's members last until the rental ends)	`nexalregions.use`
`/region remove \<player>`	Remove a member (renters only the ones they added)	`nexalregions.use`
`/region setspawn`	Set your region's teleport point	`nexalregions.use`
`/region spawn [region]`	Teleport to a region you own, rent or belong to	`nexalregions.use`
`/region listings`	Browse regions for sale or rent	`nexalregions.listings`
`/region claim`	Claim deposited rent	`nexalregions.use`
`/region transfer \<player>`	Give your region to an online player	`nexalregions.transfer`
`/region offer accept [region]`	Accept a purchase offer (name the region when you have several)	`nexalregions.use`
`/region offer decline [region]`	Decline a purchase offer	`nexalregions.use`
`/region borders`	Cycle border display: off, particles, glow (modes turned off in config are skipped)	`nexalregions.use`
`/region notifications`	Toggle entry notifications	`nexalregions.use`

Admin Commands

Command	Description	Permission
`/region admin`	Open the admin GUI (console: admin help)	`nexalregions.admin`
`/region admin help [page]`	Show admin help	`nexalregions.admin`
`/region admin create \<id>`	Create a region with the selection tool	`nexalregions.admin`
`/region admin delete \<id>`	Delete a region and its hologram	`nexalregions.admin`
`/region admin list`	List all regions (GUI)	`nexalregions.admin`
`/region admin tp \<id>`	Teleport to a region	`nexalregions.admin`
`/region admin setowner \<id> [player]`	Set the owner (blank or `server` = server-owned)	`nexalregions.admin`
`/region admin setprice \<id> \<amount>`	Set the sale price	`nexalregions.admin`
`/region admin setrent \<id> \<amount>`	Set the rent price per day	`nexalregions.admin`
`/region admin forsale \<id> <true\|false>`	Toggle for sale	`nexalregions.admin`
`/region admin forrent \<id> <true\|false>`	Toggle for rent	`nexalregions.admin`
`/region admin hologram \<id>`	Place the region's hologram where you stand	`nexalregions.admin`
`/region admin flag \<id> \<flag> <true\|false>`	Set a region flag	`nexalregions.admin`
`/region admin setname \<id> \<name>`	Set the display name	`nexalregions.admin`
`/region admin settax \<id> <amount\|default>`	Set a region's own tax, or go back to the default	`nexalregions.admin`
`/region admin evict \<id>`	Evict the renter	`nexalregions.admin`
`/region admin offer create \<id> \<player> \<price> [duration]`	Offer a region to a player; duration like `30m`, `12h`, `7d` (default `offers.default-duration`). Replaces an earlier offer of that region to that player	`nexalregions.admin`
`/region admin offer list [id]`	List pending offers, of one region or all	`nexalregions.admin`
`/region admin offer remove \<id> [player]`	Withdraw a region's offers, or only the one to a player	`nexalregions.admin`
`/region admin reload`	Reload configuration	`nexalregions.admin`
`/region admin export`	Export all data to `plugins/NexalRegions/export/`	`nexalregions.admin`
`/region admin import`	Import the files in `export/` into the current storage	`nexalregions.admin`

Commands that take a region ID also work from the console, except create, list, tp and hologram.

Permissions

Permission	Description	Default
`nexalregions.use`	Basic region commands	true
`nexalregions.buy`	Buy regions	true
`nexalregions.rent`	Rent regions	true
`nexalregions.listings`	View listings	true
`nexalregions.transfer`	Transfer ownership	true
`nexalregions.admin`	Admin commands and GUI	op
`nexalregions.bypass`	Bypass region protection	op
`nexalregions.limit.\<number>`	Region ownership limit (1 to 100)	-
`nexalregions.limit.unlimited`	Unlimited regions	op
`nexalregions.*`	All of the above except `bypass` and the limits	op

Placeholders

Requires PlaceholderAPI. Reading a placeholder never creates player data.

Player

Placeholder	Description
`%nexalregions_player_regions_owned%`	Number of owned regions
`%nexalregions_player_regions_rented%`	Number of rented regions
`%nexalregions_player_total_spent%`	Total money spent
`%nexalregions_player_total_earned%`	Total money earned
`%nexalregions_player_notifications_enabled%`	Entry notifications (Yes/No)
`%nexalregions_player_borders_enabled%`	Border display on (Yes/No)
`%nexalregions_player_border_mode%`	Border display mode (off/particles/glow)

Current Region

Placeholder	Description
`%nexalregions_current_id%`	Region ID
`%nexalregions_current_name%`	Region display name
`%nexalregions_current_owner%`	Owner name (Server, or Hidden)
`%nexalregions_current_renter%`	Renter name
`%nexalregions_current_in_region%`	In a region (Yes/No)
`%nexalregions_current_can_build%`	Can build (Yes/No)
`%nexalregions_current_is_owner%`	Is owner (Yes/No)
`%nexalregions_current_is_renter%`	Is renter (Yes/No)
`%nexalregions_current_is_member%`	Is member (Yes/No)
`%nexalregions_current_for_sale%`	For sale (Yes/No)
`%nexalregions_current_for_rent%`	For rent (Yes/No)
`%nexalregions_current_sale_price%`	Sale price
`%nexalregions_current_rent_price%`	Rent price per day
`%nexalregions_current_area%`	Region area (blocks)
`%nexalregions_current_volume%`	Region volume
`%nexalregions_current_members%`	Member count
`%nexalregions_current_rent_remaining%`	Rent time remaining
`%nexalregions_current_pvp%`	PvP enabled (Yes/No)
`%nexalregions_current_mob_spawning%`	Mob spawning (Yes/No)
`%nexalregions_current_explosions%`	Explosions enabled (Yes/No)
`%nexalregions_current_fire_spread%`	Fire spread (Yes/No)

Global

Placeholder	Description
`%nexalregions_total_regions%`	Total region count
`%nexalregions_regions_for_sale%`	Regions for sale
`%nexalregions_regions_for_rent%`	Regions for rent (without a renter)

Configuration

The most used settings can be changed in game: /region admin > Configuration.

config.yml

storage:
  type: json               # json or sql; changing it needs a restart
  sql:                     # older configs with a "mysql:" section keep working
    host: localhost
    port: 3306
    database: nexal_regions
    username: root
    password: ""

features:
  entry-notifications: true
  border-particles: true   # lets players pick particle borders
  border-glow: true        # lets players pick the glow outline (seen only by them)
  holograms: true

regions:
  default-flags:
    pvp: false
    mob-spawning: true
    explosions: false
    fire-spread: false
  limits:
    default: 1             # nexalregions.limit.\<number> and .unlimited override it

rent:
  periods:                 # period lengths in seconds
    hour-real: 3600
    day-real: 86400
    day-minecraft: 1200
  max-upfront-days: 7      # most rent time a renter can have paid ahead
  auto-renewal: true
  grace-period: 86400      # seconds of unpaid rent before eviction
  eviction-warning-interval: 3600
  reminder-times:          # seconds before rent is due
    - 86400
    - 3600
    - 600
  confirmation-expiry: 60  # seconds an upfront price stays locked
  check-interval: 60       # how often rent and taxes are processed (seconds)

taxes:
  enabled: false
  default-amount: 0        # tax per period; /region admin settax overrides it per region
  period: 604800           # 7 days
  grace-period: 172800     # 48 hours

offers:
  default-duration: 86400  # seconds an offer stays open when the command gives no duration

listings:
  mode: gui                # disabled, command or gui

holograms:
  update-interval: 100     # ticks
  lines:                   # %name%, %id%, %status%, %price%, %owner%, %renter%, %area%, %volume%
    - "%name%"
    - "%status%"
    - "%price%"
    - "%owner%"
  lines-unowned:
    - "%name%"
    - "%status%"
    - "%price%"

border-particles:
  update-interval: 10
  max-distance: 10
  particle-spacing: 0.5
  height-offset: 1.0
  colors: ["#2ECC71", "#3498DB", "#E74C3C", "#F39C12", "#9B59B6", "#1ABC9C", "#E91E63", "#00BCD4"]

border-glow:
  update-interval: 40
  max-distance: 15
  entity-spacing: 3.0
  max-entities-per-region: 60
  colors: ["BLUE", "GREEN", "RED", "GOLD", "AQUA", "LIGHT_PURPLE"]   # names or #RRGGBB

messages.yml

Every player-facing message is in messages.yml, in MiniMessage format, with optional sounds and titles. The colors are listed at the top of the file for find-and-replace:

Primary: <gradient:#5DADE2:#73B9E8> (blue)
Secondary: <gradient:#89C4EA:#9FD0F0>
Success, error, warning and info use the shared Nexal colors

The text: section at the end holds the words used inside other text: yes/no, rent period names, time units and the hologram parts.

Messages added in an update are used from the plugin's defaults until you add them to your file.

region-purchased:
  message:
    - "%prefix%<gradient:#2ECC71:#52D68A>✔ You purchased \<white>%region%\</white> for \<white>%amount%\</white>!\</gradient>"
  sound: "ENTITY_PLAYER_LEVELUP"
  title: "<gradient:#5DADE2:#73B9E8>\<bold>Region Purchased!\</bold>\</gradient>"
  subtitle: "\<gray>%region%\</gray>"
  fade-in: 10
  stay: 60
  fade-out: 20

Database Schema

With storage.type: sql the plugin creates these tables. Column names are the field names. With JSON storage the same records live in data.json, one key per table.

`regions`

Column	Type	Key	Description
`id`	VARCHAR(64)	PK	Region ID
`name`	VARCHAR(128)		Display name
`world`	VARCHAR(64)		World name
`minX`, `minY`, `minZ`	INT		Minimum corner
`maxX`, `maxY`, `maxZ`	INT		Maximum corner
`ownerId`	VARCHAR(36)		Owner UUID (null = server)
`ownerHidden`	BOOLEAN		Owner name hidden
`forSale`	BOOLEAN		Listed for sale
`salePrice`	DOUBLE		Sale price
`forRent`	BOOLEAN		Listed for rent
`rentPricePerDay`	DOUBLE		Rent price per day
`rentModeStr`	VARCHAR(16)		INSTANT or DEPOSITED
`depositedRent`	DOUBLE		Rent waiting to be claimed
`rentingDisabled`	BOOLEAN		Owner stops renting after the current rental
`renterId`	VARCHAR(36)		Current renter UUID
`renterPeriodStr`	VARCHAR(16)		HOUR_REAL, DAY_REAL or DAY_MINECRAFT
`rentPaidUntil`	BIGINT		Rent paid until (epoch ms)
`hologramId`	VARCHAR(64)		Hologram identifier
`hologramWorld`	VARCHAR(64)		Hologram world
`hologramX`, `hologramY`, `hologramZ`	DOUBLE		Hologram position
`teleportWorld`	VARCHAR(64)		Spawn world
`teleportX`, `teleportY`, `teleportZ`	DOUBLE		Spawn position
`teleportYaw`, `teleportPitch`	FLOAT		Spawn rotation
`membersJson`	TEXT		JSON array of member UUIDs; `renter:\<uuid>` for members the renter added
`flagsJson`	TEXT		JSON object of flag values
`taxEnabled`	BOOLEAN		Region has its own tax amount
`taxAmount`	DOUBLE		The region's own tax amount
`taxDueTimestamp`	BIGINT		Next tax due (epoch ms)
`createdAt`	BIGINT		Creation timestamp

`region_offers`

Column	Type	Key	Description
`id`	VARCHAR(36)	PK	Offer ID
`regionId`	VARCHAR(64)		Region
`targetPlayerId`	VARCHAR(36)		Player the offer is for
`price`	DOUBLE		Offer price
`expiresAt`	BIGINT		Expiry (epoch ms)
`createdAt`	BIGINT		Creation timestamp

`region_logs`

Column	Type	Key	Description
`id`	VARCHAR(36)	PK	Log ID
`regionId`	VARCHAR(64)		Region
`previousOwnerId`	VARCHAR(36)		Previous owner or payer
`newOwnerId`	VARCHAR(36)		New owner or renter
`logType`	VARCHAR(32)		Event type
`amount`	DOUBLE		Amount of money involved
`timestamp`	BIGINT		When it happened (epoch ms)
`description`	TEXT		Details

`region_users`

Column	Type	Key	Description
`id`	VARCHAR(36)	PK	Player UUID
`entryNotificationsEnabled`	BOOLEAN		Entry notification preference
`borderMode`	VARCHAR(20)		OFF, PARTICLES or GLOW
`totalRegionsOwned`	INT		Regions owned counter
`totalSpent`	DOUBLE		Money spent
`totalEarned`	DOUBLE		Money earned
`lastSeen`	BIGINT		Last seen (epoch ms)

Key Legend: PK = Primary Key

Saving runs on a background thread, so storage never blocks the server.

Moving between JSON and SQL

/region admin export, set storage.type, restart, /region admin import.

Dependencies

Server: Spigot or Paper 1.20.1+
Vault and an economy plugin: needed for buying, renting, rent payouts and taxes (the plugin loads without them, with those features off)
Optional: PlaceholderAPI; DecentHolograms, HolographicDisplays or FancyHolograms

nexal-core is built into the plugin JAR; there is nothing else to install.

Installation

Install Vault and an economy plugin
Place the NexalRegions JAR in your plugins folder
Restart the server
Open /region admin to adjust the settings, or edit config.yml and messages.yml
Create regions with /region admin create \<id> and list them with /region admin forsale / forrent

Rent System Details

Rent Periods

Hour: 1 real hour (rent.periods.hour-real)
Day: 24 real hours (rent.periods.day-real)
MC Day: 20 minutes, one Minecraft day (rent.periods.day-minecraft)

A period costs its share of the daily rent price: at $100 a day, an hour costs about $4.17.

Upfront Payment

/region pay [days] pays that many more days, prorated to the time actually added and capped so a renter never has more than rent.max-upfront-days (7) paid ahead: with 6.5 days left and rent at $100 a day, /region pay 7 adds half a day for $50. The price is locked for rent.confirmation-expiry seconds; run /region pay again (or click Pay Upfront again) to confirm. A different day count replaces the quote with a new one.

Auto-Renewal and Eviction

When rent is due, the next period is taken from the renter's balance. Renters get reminders at rent.reminder-times before rent is due. If they cannot pay, a grace period of rent.grace-period starts with a warning every rent.eviction-warning-interval; after it they are evicted.

Stopping Rentals

In Rent Settings, an owner stops renting a rented region: the rental ends when the time already paid runs out, is not renewed, and the renter cannot pay further ahead. Clicking again takes it back.

Price Lock Protection

An upfront rent price is locked when quoted, so an owner raising the rent in the meantime changes nothing. Buying from the GUI is refused if the price changed since the screen showed it.

Offers

An admin offers a region to one player with /region admin offer create, at any price, even when the region is owned by a player. The player is told and runs /region offer accept (or decline) from anywhere before the offer runs out; the price goes to the region's owner, as with a normal sale. A region can be offered to several players at once: the first to accept buys it, and the others' offers end, as every offer on a region does when it changes hands. /region admin > Offers lists the pending offers; shift left click withdraws one.

Taxes

With taxes.enabled, every player-owned region with a tax above 0 (its own from /region admin settax, or taxes.default-amount) is taxed each taxes.period, starting one period after it is first seen with its owner. An owner who cannot pay is warned, and after taxes.grace-period the region returns to the server.

License

Proprietary - Nexal Studios

Features​

Core Features​

Region Protection​

Rent Features​

Ownership Features​

Technologies​

Commands​

Player Commands​

Admin Commands​

Permissions​

Placeholders​

Player​

Current Region​

Global​

Configuration​

config.yml​

messages.yml​

Database Schema​

regions​

region_offers​

region_logs​

region_users​

Moving between JSON and SQL​

Dependencies​

Installation​

Rent System Details​

Rent Periods​

Upfront Payment​

Auto-Renewal and Eviction​

Stopping Rentals​

Price Lock Protection​

Offers​

Taxes​

License​