> For the complete documentation index, see [llms.txt](https://cyr1en.gitbook.io/commandprompter/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cyr1en.gitbook.io/commandprompter/configuration/presets.md). # Presets `presets.json` defines reusable prompts, post-commands, approval gates, and conditional post-commands. CommandPrompter extracts a sample file to `plugins/CommandPrompterPaper/presets.json` on first start and reloads it with `/cmdp reload`. To generate a prompt definition from inline syntax, use [`/cmdp preset add|update|remove`](/commandprompter/prompts/presets.md#create-and-manage-prompt-presets) (since 3.3.0). These commands save and activate changes immediately. Manual edits to the file require `/cmdp reload`. Use this root shape for schema-compatible files: ```json { "prompts": [], "post_commands": [], "approval_gates": [], "conditional_post_commands": [] } ``` The runtime treats an absent array as empty, although the documentation schema requires `prompts` and `post_commands`. The file is limited to 1 MiB and each array to 256 definitions. A failed load keeps the previous in-memory preset snapshot. IDs are case-sensitive, must be nonempty, and must be unique across all four definition kinds. Duplicate and cross-kind collisions reject the complete reload. Prompt and post-command IDs should not contain whitespace because `<@id>` and `` stop at the first space. Approval-gate and conditional post-command IDs must match `^[a-z0-9_.-]{1,64}$`. When drafting commands in chat, `<@` tab-completes prompt preset IDs and ``. | Field | Values and behavior | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `validator` | A nonblank, configured input-validator alias, equivalent to `-iv:alias`. An unknown alias rejects command creation/update or a flow using the preset. | | `answer_type` | `NONE` (default), `INTEGER`, or `STRING`. `INTEGER` requires an integer answer; `STRING` requires a nonblank answer. Values are uppercase and correspond to `-int`/`-str`. | | `timeout` | Integer from 1 through 3600, in seconds. Overrides the global prompt timeout, like `-timeout:N`. | | `flags` | An object of string values containing custom flags parsed from a configured screen alias. Built-in prompt keys do not parse arbitrary trailing words as custom flags. | | `break_if` | A condition equivalent to `-breakIf:expression`. Evaluated after answer validation, before accepting the candidate answers. If true, cancels the flow. | For example: ``` /cmdp preset add quantity ``` The resulting Chat preset includes this field: ```json "behavior": { "answer_type": "INTEGER", "timeout": 30, "flags": {}, "break_if": "{0} == 0" } ``` `break_if` uses zero-based answer references: `{0}` is the first answer in the command flow, including the current candidate when it is the first prompt. For a dialog, the options apply to its answer-bearing rows; layout rows contribute no answers. Conditions use the inline condition rules and do not allow PlaceholderAPI references. An evaluation error aborts the flow. The separate top-level `sanitize` and `title_display` fields continue to control sanitization and the title wrapper. Confirmation and Item presets also have their existing top-level `timeout`; conversion preserves those type-specific fields as well. ## Chat prompt Required fields are `prompt_text` and `cancel`: ```json { "type": "chat", "id": "reason", "prompt_text": "Enter a reason:", "sanitize": true, "cancel": { "send": true, "message": "[Cancel]", "clickable": true, "hover_message": "Cancel this request" } } ``` `send` controls whether the cancel component appears; `clickable` controls whether that preset component runs the cancel command. Clicking the cancel component executes `/cmdp cancel`. The `promptpaper.cancel` permission defaults to `true`, so all players can use clickable cancel controls. Typing the cancel keyword does not require any permission. ## Anvil prompt ```json { "type": "anvil", "id": "rename", "title": "Rename item", "prompt_text": "Enter a name", "sanitize": false, "left_button": { "show": true, "button_text": "New Name", "button_icon": "PAPER", "button_hover_text": "Enter the new name", "custom_model_data": 0 }, "right_button": { "show": true, "button_text": "Cancel", "button_icon": "BARRIER", "button_hover_text": "Cancel this prompt", "custom_model_data": 0 } } ``` Anvil preset fields: * `title`: Anvil window title. * `prompt_text`: Default text placed in the input rename field (falls back to `left_button.button_text` if empty). * `left_button.*`: Configures the left input item: * `show`: whether to place the item in the left slot. * `button_text`: default text / display name. * `button_icon`: material name (e.g. `PAPER`). * `button_hover_text`: lore displayed on hover. * `custom_model_data`: custom model data value. * `right_button.*`: Configures the cancel item in the right slot: * `show`: whether to enable the cancel item. * `button_text`: display name for the cancel item. * `button_icon`: material name (e.g. `BARRIER`). * `button_hover_text`: lore displayed on hover. * `custom_model_data`: custom model data value. * Submitting the result/output slot yields the rename text. `right_button` acts as the cancel button. Invalid material names fall back to `PAPER`. ## Player UI prompt ```json { "type": "player_ui", "id": "target", "prompt_text": "Choose a player", "filter": "w", "sanitize": true, "cancel_button": { "show": true, "slot": 4, "button_text": "Cancel", "button_icon": "BARRIER", "button_hover_text": "Cancel this prompt", "custom_model_data": 0 } } ``` `filter` uses the same syntax as inline Player UI prompts. `cancel_button`, `previous_button`, and `next_button` are optional overrides. When an override is absent, the YAML control is used; `show: false` hides that preset control. `slot` is 0-based within the 9-slot control row (enforced in 0–8). `button_hover_text` renders as lore on the control item (supports line breaks with `{br}` or `\n`). The Search control always comes from `prompt-config.yml`. ## Sign prompt ```json { "type": "sign", "id": "pin", "prompt_text": "Enter your PIN", "sanitize": true, "default_lines": ["Enter PIN", "", "", ""] } ``` `default_lines` is optional and should contain at most four strings. When present and nonempty, it supplies the sign contents directly. Otherwise `prompt_text` is split on `{br}` and arranged using the Sign YAML settings. `prompt_text` is not sent to chat unless the native Sign provider falls back to Chat. ## Dialog prompt A Dialog preset mirrors Paper's native dialog model: ```json { "type": "dialog", "id": "ban_form", "title": "Ban Player", "sanitize": true, "base": { "body": [ { "type": "plain_message", "content": "Review the request before confirming.", "width": 300 }, { "type": "item", "material": "BARRIER", "amount": 1 } ], "inputs": [ { "label": "Reason", "input_type": "text", "max_length": 512, "max_lines": 5, "width": 300 } ] }, "dialog_type": { "type": "confirmation", "confirm_action": { "label": "Confirm", "tooltip": "Submit the form" }, "cancel_action": { "label": "Cancel" } } } ``` ### Body `base.body` accepts: * `plain_message`: `content` plus optional `width` (1–1024). * `item`: Bukkit `material` and optional `amount` (defaults to 1 and must be positive). Invalid materials fall back to `PAPER`. ### Inputs Each `base.inputs` row requires `label` and `input_type`: | Input type | Fields | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | Optional `max_length` (1–8192), `max_lines` (1–16), and `width` (1–8192). Values default from `DialogUI`. `constraints` is ignored. | | `number` | `constraints` positions are `[min,max,step,initial]`. Missing values use YAML defaults; invalid ranges and initial values are normalized. | | `choice` | Each nonblank trimmed `constraints` value becomes one option; the first is initially selected. If none remain, one empty fallback option is inserted. | Multi-input dialog presets produce $N$ answers (one per `base.inputs` entry), which can be referenced individually via `{input:1}` through `{input:N}` in post-commands or appended in order to the dispatched command. Info-only dialogs (zero input rows) produce 0 answers. `{input:N}` indices are never shifted by layout or body rows. ### Dialog types and actions `confirmation` uses: * required schema field `confirm_action`; * optional `cancel_action`. Confirm submits the configured input row or rows. Cancel cancels the session. Missing buttons fall back to the YAML labels at runtime. `multi_action` uses: * `columns`, at least 1; * exactly one of `actions` or `actions_source`; * optional `exit_action`, which customizes the button that cancels the session. An exit button is still shown when this field is omitted, using the YAML Cancel label and tooltip. An action has required `label` and optional `tooltip` and `return`. A static action submits `return`, or its label when `return` is absent. Static action buttons do not submit `base.inputs`, so avoid mixing the two interaction models. ```json "dialog_type": { "type": "multi_action", "columns": 2, "actions": [ {"label": "Survival", "return": "survival"}, {"label": "Creative", "return": "creative"} ], "exit_action": {"label": "Cancel"} } ``` Dynamic button generation uses: ```json "actions_source": "tab_completion" ``` When `"actions_source": "tab_completion"` is configured, multi-action buttons populate dynamically from Brigadier tab-completion suggestions for the preceding command arguments. If completions are available and within the button threshold, each suggestion is rendered as a clickable button. When completions exceed the threshold or none are available, the dialog falls back to a text input field. Set `dialog_type.max_buttons` to a positive integer to override `DialogUI.Defaults.Tab.MaxButtons` for this preset. If omitted, the YAML threshold applies. Converting `` saves `"actions_source": "tab_completion"` and `"max_buttons": 12`. Leave `base.inputs` empty when using `actions_source`. That fallback is a confirmation layout using the normal Confirm and Cancel buttons; a configured `exit_action` is not used there. Native prompt dialogs keep client component actions such as `open_url` open and cannot be closed with Escape. Confirm, Cancel, Exit, and answer buttons explicitly close the screen; timeout, `/cmdp cancel`, reload, disconnect, and other server-side teardown can also close it. Opening a link does not reset `Prompt-Timeout`. ## Confirmation prompt ```json { "type": "confirmation", "id": "confirm_delete", "mode": "gui", "title": "Confirm Delete", "prompt_text": "Delete this entry?", "confirm_text": "Delete", "cancel_text": "Keep", "value_mode": false, "sound": "minecraft:block.note_block.bell", "sanitize": true, "timeout": 30 } ``` `prompt_text` is required. `mode` accepts `gui`, `dialog`, or `chat`; an omitted mode uses `ConfirmationUI.Default-Mode`. In normal gate mode, Confirm advances with zero answers and Decline cancels the flow. Set `value_mode` to `true` to contribute one `true`/`false` answer instead. `timeout` must be 1–3600 seconds. See [Confirmation Prompt](/commandprompter/prompts/confirmation-prompt.md) for inline syntax and UI configuration. ## Item prompt ```json { "type": "item", "id": "reward_item", "prompt_text": "Choose a reward", "source": "catalog", "output": "key", "category": "combat", "sound": "minecraft:block.note_block.pling", "sanitize": true, "timeout": 45 } ``` `source` accepts `inventory`/`inv`, `hand`/`mainhand`, `armor`, or `catalog` and defaults to `inventory`. `output` accepts `key`, `material`, `slot`, or `amount` and defaults to `key`. `category` is valid only for catalogs and defaults to `all`; catalog prompts cannot use `slot` output. `timeout` must be 1–3600 seconds. See [Item Selector Prompt](/commandprompter/prompts/item-selector-prompt.md) and [Item Catalogs](/commandprompter/configuration/item-catalogs.md). ## Post-command presets ```json { "id": "audit", "command": "broadcast {player} selected {input:1}", "execution_policy": "on_complete", "execute_as": "console", "delay_ticks": 20 } ``` | Field | Values | | ------------------ | --------------------------------------- | | `id` | Case-sensitive preset ID | | `command` | Command without a leading slash | | `execution_policy` | `on_complete` or `on_cancel` | | `execute_as` | `console` or `player` | | `delay_ticks` | Optional nonnegative integer, default 0 | Placeholders: * `{input}` / `{input:1}`: first answer * `{input:N}`: Nth answer, one-based * `{0}`, `{1}`, ...: zero-based answer aliases * `{player}`: prompting/target player's name * PlaceholderAPI `%...%` values when installed Append one transformer to an answer reference, for example `{input:1:upper}`, `{0:trim}`, or `{1:math(*1.5)}`. Available transformers are `upper`, `lower`, `capitalize`, `trim`, `stripcolor`, `default="..."`, `math(...)`, and `round`. Transformers cannot be chained. The preset's policy, executor, and delay override any marker or delay written on the `` reference. PlaceholderAPI values are expanded only for trusted preset actions; inline post-command strings treat `%...%` literally. ## Approval gates ```json { "id": "trade_confirm", "target": "{0}", "message": "{player} wants to trade with you. Accept?", "timeout": 30, "self_approval_policy": "auto_approve", "on_deny": { "command": "tell {player} The trade was declined.", "execute_as": "player", "delay_ticks": 0 } } ``` Place definitions in `approval_gates` and reference them with ``. `target` and `message` use `{player}` and zero-based answer placeholders. `timeout` defaults to 30 and must be 1–3600 seconds. `self_approval_policy` is `auto_approve` (default) or `require_confirm`. `on_deny` is optional; its `delay_ticks` must be 0. Gate IDs are lowercase and match `^[a-z0-9_.-]{1,64}$`. Unknown IDs and free-form inline gate definitions fail closed. See [Command Flows](/commandprompter/features/command-flows.md#approval-gates) for lifecycle details. ## Conditional post-commands ```json { "id": "large_payment", "condition": "{1} >= 500", "execution_policy": "on_complete", "if_true": { "command": "broadcast {player} sent {1}", "execute_as": "console", "delay_ticks": 0 }, "if_false": { "command": "tell {player} Payment recorded.", "execute_as": "player", "delay_ticks": 0 } } ``` Place definitions in `conditional_post_commands` and reference them with ``. `execution_policy` is `on_complete` or `on_cancel`. At least one branch is required; an omitted branch performs no action when selected. Each branch supports `command`, `execute_as`, and `delay_ticks` from 0 through 72000. Conditions use zero-based answers and support numeric comparisons, `equals`, `contains`, `startsWith`, `endsWith`, `&&`, `||`, unary `!`, and parentheses. Trusted conditions may contain PlaceholderAPI references. Invalid syntax or an unresolvable operand rejects the flow rather than being treated as false. See [Command Flows](/commandprompter/features/command-flows.md#conditional-post-commands). ## Reload and error behavior * `/cmdp preset add|update|remove` saves and activates prompt edits immediately; active sessions retain their original definitions. * `/cmdp reload` cancels active sessions and reloads the file. * A malformed reload reports the failing array position/ID and preserves the previous preset registry. * Duplicate IDs, including IDs reused by another definition kind, reject the entire reload. * Any missing referenced prompt, post-command, conditional post-command, or approval-gate preset aborts that command flow instead of dispatching the literal tag. * Repeating the same post-command preset reference dispatches that ID at most once per lifecycle event. The repository's `schema/presets.schema.json` is documentation and editor support; runtime loading does not validate the file against JSON Schema. --- # 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, and the optional `goal` query parameter: ``` GET https://cyr1en.gitbook.io/commandprompter/configuration/presets.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.