# Craftly extension format

Extensions turn a plugin's commands into guided package actions. Install the actual
plugin on the Minecraft server separately. Importing a definition does not execute
commands or install software. Review its templates before enabling it.

Download `example.yml` or `example.json` beside this guide, edit it, then use
Dashboard → Extensions → Review file → Import extension. Imported extensions start
disabled. Enable one to add its actions to the package editor. Share your exported
YAML or JSON file with another store owner; credentials and store details are not
included in exports.

## Definition

```yaml
schemaVersion: 1
id: essentials-economy
name: EssentialsX Economy
version: 1.0.0
plugin: EssentialsX
description: Give the buyer in-game money.
actions:
  - id: deposit
    name: Give money
    description: Adds money to the buyer's account.
    runAs: console
    requireOnline: false
    fields:
      - id: amount
        label: Amount
        type: number
        min: 1
        max: 1000000000
        default: "100"
    commands:
      - eco give {username} {amount}
```

`schemaVersion`, `id`, `name`, `version`, `plugin`, and `actions` are required.
`description` is optional. IDs start with a lowercase letter and contain only
lowercase letters, numbers and dashes, up to 40 characters. Action IDs must be
unique within an extension; field IDs must be unique within an action.
The built-in `luckperms` ID cannot be replaced by a custom definition.

Each action needs `id`, `name`, and one to five single-line `commands`, without
leading slashes. Optional `fields` define the action form. `runAs` is `console`
(default) or `player`. `requireOnline` defaults to false; player execution always
waits for the player to join and uses their permissions.

## Fields

Every field needs `id`, `label`, and `type`. Optional properties are `description`,
`placeholder`, and a **string** `default`. All fields are required when configuring
a package action. Values are limited to 200 characters; control characters,
newlines and braces are not allowed.

| Type | Meaning |
|---|---|
| `token` | One command argument: letters, digits, `_ . : * + / @ -`; no spaces. Suitable for group names and permission nodes. |
| `text` | One line of text. Spaces are allowed; quote the placeholder in your command template if your plugin's syntax requires quoting. |
| `number` | A finite decimal number. Optional `min` and `max` bounds. |
| `select` | A listed option. Requires `options`, an array of `{ value: "true", label: "Allow" }` entries. Values must be strings. |
| `duration` | A duration such as `30d`, `1d12h`, or `30m`. Units: `s m h d w M y`; each component must be positive. |

## Placeholders and delivery

`{username}` is reserved for the buyer's Minecraft username. Other placeholders
must exactly match declared field IDs, for example `{amount}`. Files contain
declarative templates only: JavaScript, YAML custom tags and aliases, unknown
properties, and undeclared placeholders are rejected. No regex or executable
validation code is accepted.

Actions compile to commands on the server when a package is saved. Input values
are validated against that store's enabled extension, rather than accepting a
browser's command preview. Each action also has per-package online and repetition
options. The existing Craftly Paper plugin delivers the resulting commands; no
additional Craftly plugin update is required for console actions.

Paid orders keep their delivery snapshots. Disabling or replacing an extension
does not rewrite saved package commands or paid orders. To edit a package action
from a disabled extension, enable it again or replace that action. Replacement
definitions start disabled and require explicit re-enabling.

Limits: 128 KB per file, 50 stored extensions, 30 actions per extension, 12 fields
per action, 20 package actions, and 100 compiled commands per package. Templates
and compiled commands must each fit within 300 characters.

The example uses EssentialsX command syntax. Match your server's installed plugin
and version. LuckPerms command reference: https://luckperms.net/wiki/Command-Usage