> 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/edmortars/getting-started/readme.md).

# Overview

A PinnaPrison addon that puts a **mortar** in every private mine. Players unlock it once, and from then on every block they mine has a chance to fire it: the mortar kicks back, a spinning shell flies along a smooth arc onto their mine, a target ring marks the landing spot, and the blast blows up a whole crater of blocks that pays out exactly like a PinnaPrison enchant.

Everything is packet-based and runs off the main thread, and the default mortar is built from vanilla blocks, so it works out of the box with **no resource pack**.

## What's inside

| Feature            | What it adds                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Mine placeable** | `type: mortar` in any PinnaPrison mine type: one mortar per mine, owned by the mine owner, seen by everyone in the mine    |
| **Unlock**         | Currency, leveling and permission requirements, optionally withdrawn on unlock                                             |
| **Shots**          | Chance per mined block, recoil, shell arc with trail, landing marker, explosion, flying debris, sounds and particles       |
| **Rewards**        | Block currencies, autosell, instant currencies, any greed enchant and flat per-block rewards, each with its own multiplier |
| **Upgrades**       | Fire chance, reward multiplier and explosion size, each with its own levels, values, cost curve and currency               |
| **Menus**          | Unlock and upgrades menus as PinnaPrison GUI files: fully editable, vanilla chest menus by default                         |
| **Hologram**       | Live status text above the mortar (locked / ready / reloading countdown)                                                   |
| **Mortar types**   | One file per type: different looks, prices and rewards for different mine types                                            |
| **Looks**          | Vanilla block-display model (default) or your own ModelEngine models                                                       |
| **Storage**        | YAML files by default, or a MySQL / MariaDB database shared by several servers, with `/edmortars migrate`                  |
| **Extras**         | PlaceholderAPI placeholders, a developer API with events, optional per-player languages (EdLang)                           |

## Requirements

* Paper 1.20.4+ (Java 21).
* **PinnaPrison** with the GUI, BreakRewards and placeable reload API (EdLib comes bundled inside PinnaPrison).
* Optional: **PlaceholderAPI** (placeholders), **ModelEngine** (custom models), **EdLang** (per-player languages), a **MySQL / MariaDB** database (player data shared between servers; YAML files by default).

## Quick start

1. Put `EdMortars.jar` next to PinnaPrison and restart.
2. Add the mortar to a mine type in `plugins/PinnaPrison/privatemines/mines/<type>.yml`:

   ```yaml
   placeables:
     mortar1:
       type: mortar
       mortar: default
       position: '8.5,89,-9.5,-45,0'   # x,y,z,yaw,pitch of the floor spot
   ```
3. Run `/pinna reload` (or `/edmortars reload`) and go to your mine. Move it in-game with `/mp move mortar1`.
4. Right-click the mortar to unlock it, then mine.

See [Installation](/p/edmortars/getting-started/installation.md) for the details.

## Folder

```
plugins/EdMortars/
  config.yml          global settings (threads, saving, menu behaviour)
  messages.yml        every chat message
  mortars/<id>.yml    one file = one mortar type (look, hologram, unlock, upgrades, shots, rewards)
  data/<uuid>.yml     each player's unlocks, upgrade levels and long cooldowns (storage.type: yaml)
plugins/PinnaPrison/guis/EdMortars/
  mortar-unlock.yml   the unlock menu
  mortar-upgrades.yml the upgrades menu
```