# Spells (eggs)

> How a FeatherPanel spell is built, which Pterodactyl egg formats it imports, the JSON export format, variables, config parsers and install scripts.

Source: https://featherpanel.com/docs/spells/

A spell is the template a game server is built from. It holds the Docker images, the startup command, the install
script, the variables users fill in, and the rules FeatherWings uses to edit config files and detect when the server is
up. Pterodactyl calls these eggs, and FeatherPanel reads the same format. Spells are grouped in realms (Pterodactyl's
nests), for example a Minecraft realm with Paper, Vanilla and BungeeCord spells.

For the admin screens see [Realms and spells](https://featherpanel.com/docs/admin/realms-and-spells). This page covers what goes inside a spell.

## Getting spells

- **Import a file.** In the admin area open Spells, Import Spell, pick the realm and upload the JSON. PTDL_v1 and
  PTDL_v2 eggs are accepted. Any other `meta.version` is rejected with "Unsupported egg format version".
- **Install from the marketplace.** Spells Marketplace (under FeatherCloud in the admin sidebar) lists the
  Pterodactyl community eggs from `eggs.pterodactyl.io` and installs one into a realm.
- **Write one.** Create Spell opens an editor with General, Docker, Features, Config and Script tabs. Variables are
  added after the spell is saved.

Export (`GET /api/admin/spells/{id}/export`) downloads `<spell-name>.json` in the PTDL_v2 layout. FeatherPanel adds a
`_featherpanel` block with the UUID, realm, inheritance settings, default image and variable field types. Pterodactyl
ignores that block, and FeatherPanel uses it to keep the same UUID when you import the file again.

## Fields

| Field | What it does |
| --- | --- |
| `name`, `author`, `description` | Shown in the spell lists and when creating a server. |
| `meta.update_url` | Where the spell can be fetched again for updates. |
| `docker_images` | Map of label to image. One image is marked as the default for new servers. |
| `startup` | The startup command. `{{VARIABLE}}` placeholders are replaced with server variables. |
| `features` | Tags such as `eula` or `java_version` that the spell supports. |
| `file_denylist` | Files users cannot open or edit in the file manager. |
| `config.files` | Files Wings rewrites before every start (see below). |
| `config.startup` | JSON with `done`: the console line, or lines, that mean the server has started. |
| `config.logs` | Log settings passed to Wings. |
| `config.stop` | The stop command sent to the console, `stop` when empty. A value starting with `^` sends a signal: `^C` or `^SIGINT` sends SIGINT, `^SIGTERM` and `^SIGABRT` work too, any other signal kills the container. |
| `scripts.installation` | `container`, `entrypoint` and `script` for the install script. |
| `variables` | The settings users and admins can change. |

Two FeatherPanel options sit outside the egg format: Script Privilege (run the install script as a privileged
container) and Force outgoing IP. You can also inherit configuration from another spell ("Inherit configuration from")
and copy its install script ("Copy installation script from").

## Variables

Each variable has a name, description, environment variable, default value, field type and validation rules. Field
types are `text`, `number`, `boolean`, `select` and `textarea`. Rules use the pipe syntax, for example
`required|numeric|min:1|max:65535`.

- **User Viewable** shows the variable on the server's Startup page.
- **User Editable** lets the user change it there.

Variables are passed to the container as environment variables and filled into the startup command.

## Install script

When a server is installed or reinstalled, Wings starts the script container with the server's files mounted at
`/mnt/server` and the script at `/mnt/install/install.sh`, then runs it with the entrypoint, `ash` or `bash` for
example. Write everything the server needs into `/mnt/server`.

## Config file parsers

`config.files` is a JSON object keyed by file path. Each entry has a `parser` and a `find` map of keys to new values.
Wings supports the `file`, `yaml`, `properties`, `ini`, `json` and `xml` parsers. Values can use placeholders such as
`{{server.build.default.port}}` or `{{env.SERVER_MEMORY}}`.

```json
{
  "server.properties": {
    "parser": "properties",
    "find": {
      "server-ip": "0.0.0.0",
      "server-port": "{{server.build.default.port}}"
    }
  }
}
```

## Console helpers

The server console watches the output for a missing Minecraft EULA, a Java version mismatch and a process (PID) limit
error, and offers a dialog to fix each one: accept the EULA, switch the Docker image, or explain the limit.

## Frequently asked questions

### Can I use Pterodactyl eggs in FeatherPanel?

Yes. Import accepts PTDL_v1 and PTDL_v2 egg JSON files, and spells you export use the PTDL_v2 layout, so they can go back into Pterodactyl as well.

### Why can I not delete a spell?

A spell that servers still use, or that other spells inherit configuration or an install script from, cannot be deleted. Move those servers or change the other spells first.