Advance

A Minecraft plugin enabling players to borrow materials with interest for large builds. Players request items, admins approve, and repayment is tracked with configurable penalties for missed deadlines.

Key Features

• Admin-Approved Loans: Players request materials → admins review → items granted on approval (or auto-approve mode)
• Configurable Advance Limits: Set max concurrent advances per player (default: 1)
• Interest-Based System: Amount owed increases based on quantity and repayment term
• Flexible Terms: 1 hour, 1 day, 1 week, or 1 month repayment periods
• Flexible Block Configuration: Choose between specific item lists, all obtainable blocks, or all blocks
• Search Functionality: Quick search in the GUI to find items by name
• Onboarding Tutorial: /advance onboard command guides new players through the system
• Autocollect: Optional automatic payment when picking up matching items
• Overdue Penalties: Grace period → health loss → optional death penalty
• GUI Interface: Inventory-based menus for requesting, managing, and approving advances
• Player Blocklist: Block problematic players from using the advance system
• Audit Logging: Track all admin actions for accountability
• Persistent Storage: SQLite database tracks all advances and transactions

Quick Start

For Players

0. New to Advance?

/advance onboard

Get an interactive tutorial explaining how the system works, interest rates, and how to make payments.

1. Request an Advance

/advance → Request New Advance → Pick item → Select amount → Choose term → Confirm

Tip: Use the Search button in the item menu to quickly find specific blocks by name!

2. Check Status

/advance status

Shows: item type, amount owed, amount paid, remaining balance, time left, autocollect status

3. Make Payments

• Manual: /advance pay <amount> (requires items in inventory)
• Auto: /advance autocollect on (auto-applies picked-up items to debt)

4. Avoid Penalties

• Pay before deadline
• Grace period (default: 24h) before penalties start
• Overdue = increased debt + daily health loss

For Admins

Review Requests

/advance admin

• Left-click: Approve (items given to player if online, otherwise held for pickup)
• Right-click: Deny

Manage Allowed Items

/advance items list
/advance items add <material>
/advance items add inventory  # Add all items from your inventory
/advance items remove <material>

Player Blocklist

/advance block <player> [reason]   # Block a player from using advances
/advance unblock <player>          # Unblock a player
/advance blocklist                 # View all blocked players

Audit Log

/advance auditlog              # View last 10 entries
/advance auditlog <limit>      # View last N entries
/advance auditlog <player>     # View entries for a player

Reload Config

/advance reload

Commands

Command	Description	Permission	Default
/advance	Open main menu	advance.use	All players
/advance onboard	Learn how to use Advance	advance.onboard	All players
/advance status	View advance details	advance.status	All players
/advance pay <amount>	Manual payment	advance.pay	All players
/advance autocollect <on|off>	Toggle autocollect	advance.autocollect	All players
/advance admin	Admin approval panel	advance.admin	Operators
/advance items <list|add|remove>	Manage allowed items	advance.admin.items	Operators
/advance block <player> [reason]	Block player from advances	advance.admin.blocklist	Operators
/advance unblock <player>	Unblock a player	advance.admin.blocklist	Operators
/advance blocklist	View blocked players	advance.admin.blocklist	Operators
/advance auditlog [player|limit]	View audit log	advance.admin.auditlog	Operators
/advance reload	Reload configuration	advance.admin.reload	Operators

Permissions

Permission	Description	Default
advance.use	Basic commands (grants advance.request + advance.status + advance.onboard)	true
advance.request	Request advances	true
advance.status	View status	true
advance.pay	Make payments	true
advance.onboard	Use onboard command	true
advance.autocollect	Use autocollect	true
advance.admin	Admin panel (grants all advance.admin.*)	op
advance.admin.approve	Approve requests	op
advance.admin.deny	Deny requests	op
advance.admin.items	Manage allowed items	op
advance.admin.blocklist	Manage player blocklist	op
advance.admin.auditlog	View audit logs	op
advance.admin.reload	Reload config	op

Configuration

Edit plugins/Advance/config.yml:

Allowed Items

You can configure which blocks players can request using three methods:

Option 1: Specific Item List (Default)

allowed-items:
  - STONE
  - DIRT
  - NETHERRACK
  - WHITE_WOOL

advance:
  allow_all_obtainable_blocks: false
  allow_all_blocks: false

Use Bukkit Material names (e.g., DIAMOND_ORE, not minecraft:diamond_ore). Managed in-game via /advance items add/remove.

Option 2: All Obtainable Blocks

advance:
  allow_all_obtainable_blocks: true  # Allows all survival-obtainable blocks
  allow_all_blocks: false

Automatically allows any block that can be obtained in survival mode (excludes command blocks, barriers, etc.).

Option 3: All Blocks (Use with Caution)

advance:
  allow_all_obtainable_blocks: false  # Ignored when allow_all_blocks is true
  allow_all_blocks: true  # WARNING: Allows ALL blocks including unobtainable ones

Allows every block in the game, including normally unobtainable items like command blocks and barriers. Use with caution!

Precedence: allow_all_blocks > allow_all_obtainable_blocks > allowed-items list

Auto-Approve Mode

advance:
  # When true, advance requests are automatically approved without admin review.
  # The request will still fail if the player is blocked or at max advances.
  auto_accept: false

Maximum Concurrent Advances

advance:
  # Maximum number of active advances a player can have at once.
  # Set to 1 for traditional single-advance behavior (UI remains unchanged).
  # Set higher to allow multiple concurrent advances.
  max_advances: 1

Request Limits

max-request-amount: 512  # Maximum items per request

Interest Rates

interest-calculation:
  base-rate: 0.05  # 5%
  term-multipliers:
    "1h": 1.0   # No extra interest for 1 hour
    "1d": 1.5   # 50% more interest for 1 day
    "1w": 2.0   # 100% more for 1 week
    "1m": 4.0   # 300% more for 1 month
  quantity-multiplier-per-stack: 0.01  # +1% per stack (64 items)

Formula: Interest = Amount × Base Rate × Term Multiplier × (1 + Stacks × Quantity Multiplier)

Example (64 stone, 1 day):

• Interest = 64 × 0.05 × 1.5 × 1.01 = 4.85
• Total Owed: 69 items (64 + 5 rounded)

Penalties

penalties:
  overdue-interest-increase: 0.10  # +10% debt immediately when overdue
  grace-period-hours: 24           # Time before health penalties start
  
  health-penalty:
    enabled: true
    hearts-lost-per-day: 1         # Hearts (0.5 HP) lost per day overdue
    minimum-health-hearts: 1       # Won't go below 0.5 HP
  
  final-death-penalty:
    enabled: false                 # DANGER: Kills player after max days
    max-overdue-days: 10
  
  dangerous-actions-enabled: false # MUST be true to enable death penalty

Autocollect

autocollect:
  enabled-by-default: false
  notification-style: "ACTION_BAR"  # or "CHAT"

Logging

logging:
  level: "INFO"              # INFO, WARNING, or SEVERE
  log-player-names: false    # Privacy: log only UUIDs if false
  log-amounts: true          # Log transaction amounts

How It Works

1. Request: Player selects item, amount, and term → calculates total owed (principal + interest)
2. Approval: Admin reviews → approves/denies → items given to player
3. Repayment: Player pays with manual commands or autocollect
4. Completion: Debt paid → advance closes → player can request again
5. Penalties: Miss deadline → grace period → overdue interest → health loss → (optional) death

Status Progression: PENDING → APPROVED → PAID (or DENIED, EXPIRED)