Advance

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

- Persistent Storage: Players request materials → admins review → items granted on approval (or auto-approve mode) - Persistent Storage: Set max concurrent advances per player (default: 1) - Persistent Storage: Amount owed increases based on quantity and repayment term - Persistent Storage: 1 hour, 1 day, 1 week, or 1 month repayment periods - Persistent Storage: Choose between specific item lists, all obtainable blocks, or all blocks - Persistent Storage: Quick search in the GUI to find items by name - Persistent Storage: `/advance onboard` command guides new players through the system - Persistent Storage: Optional automatic payment when picking up matching items - Persistent Storage: Grace period → health loss → optional death penalty - Persistent Storage: Inventory-based menus for requesting, managing, and approving advances - Persistent Storage: Block problematic players from using the advance system - Persistent Storage: 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.

Search ``` /advance → Request New Advance → Pick item → Select amount → Choose term → Confirm ``` Search: 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

Auto - Auto: `/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) ```yaml 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 ```yaml 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.).

Use with caution! ```yaml 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

```yaml 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

```yaml 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

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

Interest Rates

```yaml 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)`

Total Owed: 69 items (64 stone, 1 day): - Interest = 64 × 0.05 × 1.5 × 1.01 = 4.85 - Total Owed: 69 items (64 + 5 rounded)

Penalties

```yaml 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

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

Logging

```yaml 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. Penalties: Player selects item, amount, and term → calculates total owed (principal + interest) 2. Penalties: Admin reviews → approves/denies → items given to player 3. Penalties: Player pays with manual commands or autocollect 4. Penalties: 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`)