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 (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:

{
  "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 <!@id> 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 <!@ tab-completes post-command preset IDs.

Common prompt fields

Every prompt has:

Field	Required	Description
type	Yes	chat, anvil, player_ui, sign, dialog, confirmation, or item
id	Yes	Unique prompt ID
sanitize	No	When true (default), answers are sanitized (color codes and special characters stripped). When set to false, answers retain legacy color codes and formatting symbols.
title_display	No	Shows an Adventure title before opening the prompt.
behavior	No	Shared execution options: validator, answer type, timeout, flags, and early termination.

title_display supports:

"title_display": {
  "main": "Review Request",
  "sub": "Complete every field",
  "ticks": 70
}

main is required by the schema; an empty value uses the prompt's normal display text. sub and ticks are optional. The screen opens after 70 ticks when ticks is omitted, and that delay counts against Prompt-Timeout.

Execution options

The optional behavior object is supported by every prompt type. /cmdp preset add and update write it when the parsed inline prompt carries execution options. Those options also apply when the prompt is referenced as <@id>.

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 <Quantity -int -timeout:30 -breakIf:{0} == 0>

The resulting Chat preset includes this field:

"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:

{
  "type": "chat",
  "id": "reason",
  "prompt_text": "Enter a reason:",
  "sanitize": true,
  "cancel": {
    "send": true,
    "message": "<gray>[<red>Cancel</red>]</gray>",
    "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

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

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

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

{
  "type": "dialog",
  "id": "ban_form",
  "title": "Ban Player",
  "sanitize": true,
  "base": {
    "body": [
      {
        "type": "plain_message",
        "content": "<gray>Review the request before confirming.</gray>",
        "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": "<green>Confirm</green>",
      "tooltip": "Submit the form"
    },
    "cancel_action": {
      "label": "<red>Cancel</red>"
    }
  }
}

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.

"dialog_type": {
  "type": "multi_action",
  "columns": 2,
  "actions": [
    {"label": "Survival", "return": "survival"},
    {"label": "Creative", "return": "creative"}
  ],
  "exit_action": {"label": "Cancel"}
}

Dynamic button generation uses:

"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 <d:tab[12]:Choose> 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

{
  "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 for inline syntax and UI configuration.

Item prompt

{
  "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 and Item Catalogs.

Post-command presets

{
  "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 <!@id> reference. PlaceholderAPI values are expanded only for trusted preset actions; inline post-command strings treat %...% literally.

Approval gates

{
  "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 <!gate:@trade_confirm>. 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 for lifecycle details.

Conditional post-commands

{
  "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 <!@large_payment>. 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.

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.