> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/pinnablockselector/getting-started/readme.md).

# Overview

A **PinnaPrison** addon that lets players choose the blocks their private mine is made of. Players who unlocked the **Block Selector** pick up to 4 blocks (configurable) from every solid block in the game; while they have blocks chosen, their mine is filled with them instead of the blocks of its upgrade tier. Clearing the choice brings the tier blocks back. Visitors and mine members see the owner's blocks.

Everything runs through PinnaPrison: the menus are regular PinnaPrison GUI files, the price is any PinnaPrison currency, and the chosen blocks sell through PinnaPrison's `autosell.yml` like any other mine block.

## Features

* A paginated chest menu with every placeable full block (plus glass, leaves, ice, slime and honey), in game order, with category filters (stone, ores, wood, colourful, nature, nether & end, others) or category tabs.
* Up to 64 choice slots (4 by default), edited freely: nothing touches the mine until the player presses **Apply**, then the mine refills at once. An apply cooldown stops refill spam.
* Unlock it in game with any PinnaPrison currency (a confirm menu with price and balance), from the console (store, crates, votes), or with a rank permission.
* Rank-only categories: lock a category's blocks behind a permission (VIP blocks).
* Weighting: split the mine evenly, or make block #1 the most common; add extra blocks (like an income beacon) to every custom mine.
* Season reset support: keep the unlock and choices forever, or clear them on `/pinna restoreall`.
* A button for your `/mine` menu that opens the selector, or the purchase menu while it is locked.
* Every message, sound, number and menu is configurable. PlaceholderAPI placeholders. EdLang support.
* Local YAML storage, or MySQL / MariaDB to share unlocks and choices between servers, with a migrate command.
* A developer API with events.

## Requirements

* Paper 1.21+ (Java 21).
* **PinnaPrison 1.2.30 or newer** (required: private mines, currencies and menus are PinnaPrison's).
* Optional: **PlaceholderAPI** (placeholders), **EdLang** (per-player languages).

## Quick start

1. Put `PinnaBlockSelector.jar` in `plugins/` next to PinnaPrison and restart.
2. Set the price in `plugins/PinnaBlockSelector/config.yml` → `purchase` (currency id and amount) and run `/blockselector reload`.
3. Add the Block Selector button to PinnaPrison's `/mine` menu (`plugins/PinnaPrison/guis/mine.yml`), see [Menus](/p/pinnablockselector/reference/guis.md#the-mine-button), then `/pinnaprison reload`.
4. Optional: give a rank `pinnablockselector.unlock`, or sell it in your store with `blockselector give {player} -s`.
5. Players open `/blockselector`, click blocks, and press **Apply**.

## Folder

```
plugins/PinnaBlockSelector/
  config.yml          blocks, categories, mine weights, purchase, cooldown, season reset, sounds, storage
  messages.yml        every chat message
  data/players.yml    who unlocked it and the blocks each player chose (storage.type: yaml)
plugins/PinnaPrison/guis/pinnablockselector/
  blockselector.yml      the selector menu
  blockselector-buy.yml  the purchase menu
```