> 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/pinnaprison/core/schematics.md).

# Schematics & Mine Setup

A **mine type** is defined by two things:

1. A **schematic** — the build (`.pinna` file in `schematics/`) that is pasted as packets for every mine of this type.
2. A **mine type file** — `privatemines/mines/<id>.yml` — which describes the mineable area, spawn, block list, decorations and expansion limit.

The filename (without `.yml`) is the mine type **id** (e.g. `default`). The `default-mine` in `privatemines/config.yml` sets which type new players get.

## Creating a schematic in-game

Schematics are created and saved entirely in-game with `/pinna setupmine`. The `.pinna` format is **cross-version** — a schematic saved on one supported version works on all of them.

| Step | Command                               | What it does                                                       |
| ---- | ------------------------------------- | ------------------------------------------------------------------ |
| 1    | `/pinna setupmine <id>`               | Start a setup session for mine type `<id>`.                        |
| 2    | `/pinna setupmine min`                | Set the **minimum** corner of the mineable cuboid (your position). |
| 3    | `/pinna setupmine max`                | Set the **maximum** corner of the mineable cuboid (your position). |
| 4    | `/pinna setupmine spawn`              | Set the spawn point players teleport to (your position + facing).  |
| 5    | `/pinna setupmine expansion <amount>` | Set the max expansion size for this mine type.                     |
| 6    | `/pinna setupmine finish`             | Save the schematic + generate `privatemines/mines/<id>.yml`.       |
| –    | `/pinna setupmine cancel`             | Abort the current session.                                         |

{% hint style="info" %}
Build your mine somewhere in a normal world, run through the steps above, and PinnaPrison captures the build into a `.pinna` schematic and writes the matching mine type file for you.
{% endhint %}

## The mine type file

`privatemines/mines/default.yml`:

```yaml
name: 'Default'
schematic: 'default'

spawn:
  x: 16.46
  y: 89.0
  z: -54.55
  yaw: 0.36
  pitch: -4.89

min-corner: { x: 11, y: 31, z: -5 }
max-corner: { x: 21, y: 87, z: 5 }

max-expansion: 34

block-types:
  '1':
    STONE: 70
    COBBLESTONE: 30
    BEACON: 1
  '2':
    COBBLESTONE: 50
    ANDESITE: 30
    DIORITE: 20
    BEACON: 1

placeables:
  '1':
    type: hologram
    # …
  '2':
    type: entity
    # …
```

| Key                         | Description                                                         |
| --------------------------- | ------------------------------------------------------------------- |
| `name`                      | Display name of the mine type.                                      |
| `schematic`                 | The `.pinna` file (in `schematics/`) used for the build.            |
| `spawn`                     | Where players teleport when they enter this mine (x/y/z/yaw/pitch). |
| `min-corner` / `max-corner` | The mineable cuboid (the blocks that can be broken and refilled).   |
| `max-expansion`             | How far players can expand this mine type.                          |
| `block-types`               | Numbered block **upgrades** — each entry is a weighted block list.  |
| `placeables`                | Decorations placed in the mine: holograms and NPCs.                 |

### Block types (mine upgrades)

`block-types` is a numbered map of weighted block lists. Index `'1'` is the starting block set; higher indexes are unlocked as the player upgrades their mine's block tier. Each line is `MATERIAL: weight` — weights are relative, so in tier `'1'` above blocks roll \~70% Stone / \~30% Cobblestone with a rare Beacon.

```yaml
block-types:
  '3':
    GRANITE: 40
    DIORITE: 30
    ANDESITE: 30
    BEACON: 1
```

## Placeables

Placeables are packet decorations shown to anyone viewing the mine. Two types are supported.

### Hologram

```yaml
'1':
  type: hologram
  position: '16.5,91,-40.5,-140,0'   # x,y,z,yaw,pitch
  update-interval: 20                # ticks between refreshes (20 = 1s)
  bar-completed: '&b█'
  bar-uncompleted: '&8█'
  bar-length: 16
  hologram:
    - '&b&l✦ &f&l{mine-owner}''s Mine &b&l✦'
    - '&b❖ &7Mine: &f{mine-type} &8• &7Size: &f{mine-size}x{mine-size}'
    - '&7Mined &f{percent-mined}% &8(&f{blocks-mined}&8/&f{blocks-total}&8)'
    - '{percent-mined-bar}'
```

A floating text display. Lines refresh on `update-interval` and update **in place** (no flicker). Available local placeholders (always evaluated for the mine **owner**):

```
{mine-owner} {mine-type} {mine-size} {mine-tax}
{percent-mined} {percent-remaining} {percent-mined-bar}
{blocks-mined} {blocks-remaining} {blocks-total}
```

PlaceholderAPI (`%...%`) and `{player}` also work.

### Entity / NPC

```yaml
'2':
  type: entity
  entity: 'PLAYER'              # any EntityType, or PLAYER / npc:true for a skinned NPC
  position: '12.5,88,-49.5'    # x,y,z (optionally ,yaw,pitch)
  npc-name: '&cAutominers'      # name above the head (<= 16 chars)
  skin-name: '{player}'         # copy a player's skin by name; {player} = mine owner
  texture: ''                   # OR a base64 texture (used only when skin-name is empty)
  signature: ''                 # Mojang signature for the texture
  left-click-commands:
    - 'player autominers'
  right-click-commands:
    - 'player autominers'
```

A packet entity — either a vanilla mob (`entity: ZOMBIE`) or a **skinned player NPC** (`entity: PLAYER` or `npc: true`). Clicks run the configured action lines.

* **`skin-name`** — copies that player's skin by name (fetched signed from Mojang, no signature needed). `{player}` / `%player_name%` = the mine owner, so the NPC can wear the owner's skin.
* **`left-click-commands` / `right-click-commands`** — [action lines](/p/pinnaprison/customization/item-format.md#actions) (`player`, `console`, `message`, `give-eco`). `{player}` is replaced with the clicker.

{% hint style="info" %}
NPCs are fully packet-based and never saved as real entities. The name above the head can use colours; PinnaPrison keeps the colour on the client while giving the backing entity a safe name internally.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://edseries-plugins.gitbook.io/p/pinnaprison/core/schematics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.