Skip to main content

Operations & Maintenance

This guide details maintenance, troubleshooting, and operational procedures for server administrators.

Startup Verification and Safety Checks​

During server startup, MapArt Land Rental executes database schema migrations and rebuilds its in-memory state cache. Until this process completes, all persistent modifications are rejected.

Verification Checklist​

  • Verify that [MapArtLandRental] MapArt Land Rental is ready appears in the server log.
  • If Vault or the Economy provider is unreachable, new rentals and paid extensions are temporarily disabled, while active lease protection and expiration routines continue running safely.
  • If database initialization encounters a fatal error, the plugin disables itself to avoid unsafe or unrecorded rentals.

Plot Reset Mechanics & Failure Recovery​

Plot resets are triggered when a lease is released or when a grace period expires.

Reset Internals​

  • Section-Level Restoration: The plugin avoids Paper's unsupported chunk regeneration API. Instead, it iterates through chunk sections within the plot bounds and restores non-empty sections plus the required floor sections.
  • Floor State Restoration: Places BEDROCK at base-y - 1, the configured world.base-material at base-y, and fills all other vertical positions with AIR.
  • Safe Player Evacuation: Any players inside the plot are safely evacuated via their Entity Schedulers.
  • Idempotence & Resume Capability: The reset process converges to the same clean state regardless of how many times it runs. If the server shuts down mid-reset, the task resumes automatically upon restart.

Handling Reset Failures​

If an unexpected I/O error or world-unloading event interrupts a reset, the plot is placed in a RESET_FAILED state. The plot remains locked to prevent re-allocating a dirty canvas to another player.

To recover a failed plot:

  1. Inspect the server log to resolve the underlying cause (e.g., missing world files or chunk load errors).
  2. Check the lease details via /mapart admin lease <id> or the Admin GUI.
  3. Trigger a manual reset retry:
/mapart admin retry-reset <Lease-ID>

Upon successful completion, the database updates and the plot returns to the free pool (FREE).

Economy Reconciliation​

External economy calls and local database writes cannot share a single ACID transaction. MapArt Land Rental prevents financial inconsistencies using a two-phase update pattern:

sequenceDiagram
    participant P as Plugin
    participant DB as Database
    participant E as Vault (Economy)

    P->>DB: 1. Record PENDING transaction
    P->>E: 2. Withdraw player balance
    alt Withdrawal Succeeded
        P->>DB: 3. Create Lease & Mark COMPLETED
    else DB Commit Failed
        P->>E: 4. Attempt compensating refund
        P->>DB: 5. Mark REFUNDED
    end

Unresolved Transactions​

If the server crashes during an external Economy API call, a transaction may be left in PENDING state. After an unexpected shutdown or economy outage, check for unresolved records:

/mapart admin transactions

Inspect your economy plugin's transaction log and player balances to determine whether money was deducted, then record your resolution:

# Confirmed no balance was withdrawn
/mapart admin transaction resolve <ID> failed confirm

# Confirmed a refund occurred or was processed manually
/mapart admin transaction resolve <ID> refunded confirm

# Keep unresolved for further review
/mapart admin transaction resolve <ID> review confirm
Reconciliation commands do not touch balances

The resolve command only updates the audit status in the database. To prevent double charges or accidental duplicate refunds, it never executes automated transactions on the economy provider.

Database Backups​

SQLite​

Stop the server or disable the plugin before copying the database files. Always copy all three files together:

  • mapart.db
  • mapart.db-wal (Write-Ahead Log)
  • mapart.db-shm (Shared Memory)

MySQL​

Use standard transaction-consistent database dump utilities (such as mysqldump --single-transaction).

Do not alter schema_version

The schema_version table tracks applied database migrations. Never delete or manually modify rows in this table.

In-Game Inspection & Force Release​

Inspect Current Location​

Stand at any location in the map art world and run:

/mapart admin inspect

This reveals the Plot Type, index, lease status, and current tenant project.

Force Release a Lease​

Administrators can forcibly terminate an abandoned or violating lease:

/mapart admin force-release <Lease-ID>

Re-run with confirm within 30 seconds to confirm the release and initiate an immediate plot reset:

/mapart admin force-release <Lease-ID> confirm