Spells (eggs)

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

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. 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

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}}.

{
  "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.