From 7d0f6a283d48954b97f787a41eab75d7767f0352 Mon Sep 17 00:00:00 2001 From: loki5512344 Date: Sun, 31 May 2026 23:26:59 +0200 Subject: [PATCH] Add comprehensive README.md with documentation - Commands table with permissions and descriptions - Permissions hierarchy documentation - PlaceholderAPI placeholders list with examples - Configuration examples (defaults.yml) - Usage examples for common workflows - WorldGuard auto-region setup instructions --- README.md | 219 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..dd1679d --- /dev/null +++ b/README.md @@ -0,0 +1,219 @@ +# LoMines + +Advanced mine management plugin for Paper 1.21.4+ + +## Features + +- **Multiple fill modes**: Cuboid (fill entire region) or Mask (fill marked positions only) +- **Weighted block system**: Configure different blocks with spawn chances +- **Automatic resets**: Timer-based or percentage-based triggers +- **WorldGuard integration**: Auto-create regions for new mines +- **PlaceholderAPI support**: Display mine info in other plugins +- **GUI editor**: In-game mine configuration editor +- **Player statistics**: Track blocks mined, mines reset, playtime + +## Commands + +### Admin Commands + +| Command | Permission | Description | +|---------|------------|-------------| +| `/lm create ` | `lomines.admin.create` | Create a new mine | +| `/lm delete ` | `lomines.admin.delete` | Delete a mine | +| `/lm reset [silent]` | `lomines.admin.reset` | Reset a mine manually | +| `/lm reload` | `lomines.admin.reload` | Reload all mine configs | +| `/lm list` | `lomines.admin.list` | List all mines | +| `/lm edit ` | `lomines.admin.edit` | Open GUI editor for a mine | +| `/lm setteleport ` | `lomines.admin.setteleport` | Set teleport location (your current position) | +| `/lm setspawn ` | `lomines.admin.setspawn` | Set safe spawn location for stuck players | +| `/lm clearspawn ` | `lomines.admin.setspawn` | Clear spawn location | +| `/lm maskscan ` | `lomines.admin.maskscan` | Scan mask marker blocks | + +### Player Commands + +| Command | Permission | Description | +|---------|------------|-------------| +| `/lm stats [player]` | `lomines.stats` | View mining statistics | +| `/lm top [mine] [limit]` | `lomines.stats` | View leaderboard | + +### Wand Commands + +| Command | Permission | Description | +|---------|------------|-------------| +| `/lm wand` | `lomines.admin.wand` | Get the region selection wand | +| `/lm group ` | `lomines.admin.wand` | Create mines from group wand selections | + +## Permissions + +```yaml +lomines.admin: + description: All admin commands + default: op + children: + lomines.use: true + lomines.admin.create: true + lomines.admin.delete: true + lomines.admin.reset: true + lomines.admin.reload: true + lomines.admin.list: true + lomines.admin.edit: true + lomines.admin.setteleport: true + lomines.admin.setspawn: true + lomines.admin.maskscan: true + lomines.admin.wand: true + lomines.stats: true + lomines.stats.others: true + +lomines.use: + description: Basic usage + default: true + +lomines.stats: + description: View own stats and leaderboards + default: true + +lomines.stats.others: + description: View other players' stats + default: op +``` + +## Placeholders (PlaceholderAPI) + +### Mine Information + +| Placeholder | Description | Example | +|-------------|-------------|---------| +| `%lomines_mine__name%` | Mine name | `mymine` | +| `%lomines_mine__blocks%` | Current blocks | `8542` | +| `%lomines_mine__total%` | Total volume | `10000` | +| `%lomines_mine__percent%` | Fill percentage (1 decimal) | `85.4` | +| `%lomines_mine__percentint%` | Fill percentage (integer) | `85` | +| `%lomines_mine__world%` | World name | `world` | +| `%lomines_mine__remaining%` | Remaining blocks | `1458` | +| `%lomines_mine__resettime%` | Time since reset (mm:ss) | `03:45` | +| `%lomines_mine__resetseconds%` | Seconds since reset | `225` | + +### Player Statistics + +| Placeholder | Description | Example | +|-------------|-------------|---------| +| `%lomines_player_blocksmined%` | Total blocks mined | `15234` | +| `%lomines_player_minesreset%` | Mines reset count | `45` | +| `%lomines_player_playtime%` | Formatted play time | `2h 15m` | +| `%lomines_player_rank%` | Leaderboard rank | `3` | + +### Global + +| Placeholder | Description | Example | +|-------------|-------------|---------| +| `%lomines_count%` | Total number of mines | `12` | + +## Configuration + +### defaults.yml + +Default configuration applied to all mines: + +```yaml +# Reset settings +reset: + interval: "5m" # Reset interval (30s, 5m, 2h, 1d) + percent-trigger: 10.0 # Trigger reset when X% of blocks mined + percent-enabled: false # Enable percentage trigger + commands: [] # Commands to run on reset + broadcast: "" # Broadcast message on reset + +# Block settings +blocks: + fill-mode: CUBOID # CUBOID or MASK + mask: + marker: "pink_concrete" # Marker block for mask mode + +# Teleport settings +teleport: + enabled: false + location: "" + +# Safe spawn for stuck players +player-spawn: + enabled: false + location: "" + +# UI settings +ui: + actionbar: + enabled: true + format: "{mine} {percent}% ({time})" + range: 50.0 + +# WorldGuard integration +worldguard: + enabled: false + region-template: "{mine_name}_{random_4}" + owners: [] + members: [] + flags: + - "passthrough=deny" + - "build=allow" +``` + +## Usage Examples + +### Creating a Simple Mine + +```bash +# 1. Get the wand +/lm wand + +# 2. Select two corners (left and right click) +# 3. Create the mine +/lm create mymine + +# 4. Edit the config file or use GUI +/lm edit mymine +``` + +### Setting Up Teleport + +```bash +# Stand where players should be teleported +/lm setteleport mymine + +# Stand where STUCK players should spawn (optional, falls back to teleport location) +/lm setspawn mymine +``` + +### Using Mask Fill Mode + +```bash +# 1. Paint positions with pink_concrete (or configured marker) +# 2. Scan the markers +/lm maskscan mymine + +# Mine will now only fill at marked positions +``` + +### WorldGuard Auto-Regions + +Enable in `plugins/LoMines/mines/_defaults.yml`: + +```yaml +worldguard: + enabled: true + region-template: "mine_{mine_name}_{random_4}" + flags: + - "passthrough=deny" + - "build=allow" +``` + +When you create a mine, a WorldGuard region `mine_mymine_7392` is automatically created. + +## Support + +- Paper 1.21.4+ +- Java 21+ +- Optional: PlaceholderAPI, WorldGuard + +## License + +MIT License