Plugin Configuration

Global settings and fixes available in the plugin's config.yml file.

Fixes & Patches

fixes.fakeinternaldata

Boolean

Enables a patch for Denizen's fakeinternaldata command on Minecraft 1.21 and higher. This patch is provided because the Denizen developers still haven't fixed this command on newer game versions. Default is true.

config.yml

fixes:
  fakeinternaldata: true

Overview & Core Setup

Dialog script containers allow you to define native Paper API UI screens rendered on the client side.

Anatomy of a Script

Structure

my_dialog:
  type: dialog
  base:
    type: multi
    title: <gold>Header Title
  bodies: ...
  inputs: ...
  buttons: ...

Dynamic Generation (Procedural)

You can define a procedural: script section at the root of the container. This executes a Denizen queue in parallel when opening the dialog, allowing you to dynamically construct and determine maps for inputs, bodies, or buttons.

Any statically defined elements in the dialog container (such as a static submit button) will be cleanly merged with your procedurally generated maps.

Note: You can naturally use click-time tags like <context.connection> or <context.button_id> inside your dynamic scripts; they are automatically escaped at load-time to prevent premature execution.

Universal Base Properties

typeRequired

The layout engine: multi, list, confirm, or notice.

titleRequired

The main header. Supports tags and MiniMessage.

external titleOptional

The window title in the client's OS frame.

can close with escapeOptional

Boolean. If true (default), ESC closes the window.

after actionOptional

Action behavior after dialog completion. Options: CLOSE (default - closes and returns to previous screen), NONE (keeps current screen open), or WAIT_FOR_RESPONSE (shows a waiting screen).

Conditional Rendering

Inputs, body elements, and buttons can be dynamically shown or hidden using the condition key. It evaluates a Denizen tag and requires it to return true to show the element.

Example

bodies:
  1:
    type: message
    condition: <player.inventory.contains_item[diamond]>
    message: <gray>You have a diamond in your inventory, so cool!

showdialog

- showdialog [<dialog>] (def:<ListTag>)

Opens a custom Paper-native dialog UI screen for the player attached to the script queue.

dialogRequired

The exact name of the dialog script container to display.

defOptional

An optional list of values to pass as parameter definitions into the dialog. In the target dialog container, these definitions are assigned to definition names in matching order (e.g. definitions: quest_id|reward).

Usage

- showdialog MySimpleDialog
- showdialog QuestConfirmDialog def:quest_01|1000

Layout: Multi

A versatile form layout. Supports multiple inputs and custom buttons.

Multi-specific `base:` Properties

columnsOptional

Integer. Arrange elements into grid columns.

exit buttonOptional

A button definition block used as a dedicated close button.

Multi-specific Root Properties

buttons:Required

A map of action buttons at the bottom.

Layout: List

Designed to display buttons that open other dialog scripts.

List-specific `base:` Properties

columnsOptional

Integer. Columns in the grid.

button widthOptional

Integer. Sets a fixed pixel width for auto-generated buttons.

exit buttonOptional

A button definition block used as a dedicated close button.

List-specific Root Properties

dialogs:Required

A list of script names to display.

Layout: Confirm

A simple confirmation box with two actions.

Confirm-specific Root Properties

yes:Root

Affirmative ActionButton definition.

no:Root

Negative ActionButton definition.

Layout: Notice

A simple alert box.

Notice-specific Root Properties

button:Root

Optional ActionButton definition. If omitted, creates a default "OK" button.

Components: Inputs

Inputs defined under inputs:. Values available via <context.key_name>.

Universal Input Properties

conditionOptional

A boolean tag. If it evaluates to false, the input field will not be shown.

Text Input (type: text)

width

Field width.

max length

Limit characters.

initial

Default text.

label visible

Boolean. Show/Hide the label.

multiline options

Section with max lines and height.

Boolean Input (type: boolean)

initial

Default state (true/false).

on true / on false

Labels for ON/OFF states.

Number Input (type: number)

start / endReq

Range bounds (Float).

step

Increment step.

initial

Starting value.

width

Slider width.

label format

Format string (e.g. "Val: %s").

Single Choice (type: single)

options:Req

Map of options (id, display, initial).

label visible

Boolean.

Components: Bodies

Defined under bodies: root key.

Universal Body Properties

conditionOptional

A boolean tag. If it evaluates to false, the body element will not be shown.

Body Types

type: message

• message: The text.
• width: Fixed width.

type: item

• item: ItemTag.
• width / height: Visual size.
• show tooltip / decorations: Booleans.
• description: Nested message-type body.

Buttons & Actions

Common properties and action types.

labelReq

Button text.

tooltip

Hover text.

width

Button width.

conditionOptional

A boolean tag. If it evaluates to false, the button will not be shown.

Action Types (type:)

SCRIPT

Key: script:. Runs Denizen commands.

Available Contexts:
<context.connection> - The ConnectionTag of the player.
<context.button_id> - The ID of the clicked button.
<context.namespace> - The namespace (e.g. 'denizen').
<context.inputs> - MapTag of all active inputs.
<context.[input_id]> - Directly access typed value of an input field.

RUN_COMMAND

Key: command:. Runs a player command. Must include slash (/).

OPEN_URL

Key: url:. Opens a link.

COPY_TO_CLIPBOARD

Key: text:. Copies text.

Full Example

staff_application.dsc

st:
  type: dialog
  base:
    type: multi
    title: <yellow>Staff Application
    columns: 1
  bodies:
    header:
      type: message
      message: <gray>Please fill out the form below carefully.
  inputs:
    1:
      type: text
      label: Your Real Name
      key: applicant_name
    2:
      type: number
      label: Your Age
      start: 13
      end: 99
      initial: 18
      step: 1
      key: applicant_age
    has_experience:
      type: boolean
      label: Previous Experience?
  buttons:
    1:
      label: <green>Submit Application
      script:
        - narrate "Name: <context.applicant_name>"
        - narrate "Age: <context.applicant_age>"
        - narrate "Experience: <context.has_experience>"
    2:
      type: OPEN_URL
      label: Join Support Discord
      url: https://discord.gg/example

player connection configure

on player connection configure:

Triggers when a player's connection is being configured (Paper specific).

Contexts

<context.connection>ConnectionTag

Returns the ConnectionTag associated with the joining player.

<context.reflect_event>JavaReflectedObjectTag

Returns a JavaReflectedObjectTag of the raw internal event.

Determinations

WAIT:<DurationTag>Determine

Delays the configuration process by the specified duration (e.g. WAIT:1m). During this time, you can show Dialogs or process backend tasks. If no WAIT determination is specified, the configuration process completes immediately.

player custom click

on player custom click:

Triggers when a player clicks a button in a PaperMC Dialog UI.

Switches

button_id:<id>

Only process the event if the clicked button's ID matches the given text.

namespace:<name>

Only process the event if the dialog's namespace matches the given text (e.g. 'denizen').

Contexts

<context.connection>ConnectionTag

Returns the ConnectionTag of the player who clicked.

<context.button_id>ElementTag

Returns the ID of the button that was clicked.

<context.namespace>ElementTag

Returns the namespace of the dialog (e.g. 'denizen').

<context.inputs>MapTag

Returns a MapTag of all inputs and their current values.

<context.[input_key]>ElementTag

Returns the specific value of a dialog input directly by its key.

<context.reflect_event>JavaReflectedObjectTag

Returns the underlying PlayerCustomClickEvent.

BiomeTag

Additions for interacting with Biomes.

Tags

<BiomeTag.attribute[<name>]>

Returns the value of the specified environment attribute for this biome.
Valid attribute names correspond to the Minecraft EnvironmentAttributes API.
See: Environment_attribute.
Example: <player.location.biome.attribute[sky_color]>

Mechanisms

attributeInput: MapTag

Sets one or more environment attributes for this biome.
Valid attribute names correspond to the Minecraft EnvironmentAttributes API.
See: Environment_attribute.
Example: - adjust <biome[plains]> attribute:[sky_color=red;fog_color=<color[green]>]

ConnectionTag

Methods and properties for interacting with client connections.

Tags

<ConnectionTag.is_connected>ElementTag(Boolean)

Returns whether this connection is currently open and active.

<ConnectionTag.uuid>ElementTag

Returns the player profile's UUID associated with this connection.

<ConnectionTag.name>ElementTag

Returns the player profile's name associated with this connection.

<ConnectionTag.version>ElementTag

Returns the client release version name (such as "1.21.1" or "26.2") associated with this connection.
Append .protocol (as in <ConnectionTag.version.protocol>) to return the numeric protocol version ID instead (e.g. 767).
Works seamlessly during both the configuration stage (before player spawn) and normal gameplay.

Mechanisms

connectInput: None

Confirms the connection and allows the player to continue the login process. Use this to finish the configuration stage once your requirements are met.

disconnectInput: ElementTag

Disconnects the connection with a specified reason. Supports Paper-formatted text.

reconfigureInput: None

Completes the configuration for this player, causing them to reenter configuration/game phase.

transferInput: ElementTag

Natively transfers the client to another Minecraft server (host or host:port) using Minecraft 1.20.5+ Transfer Packet without needing BungeeCord/Velocity. Example: transfer:play.example.com:25565.

show_dialogInput: ScriptTag

Shows a specific dialog to the connection using the exact name of a Dialog script container.

close_dialogInput: None

Closes any currently open dialog for this specific connection.

PlayerTag

Additions for interacting with Players.

Tags

<PlayerTag.connection>ConnectionTag

Returns the active ConnectionTag associated with this online player. Allows accessing network connection mechanisms and tags directly from a PlayerTag. Example: <player.connection.version>.

<PlayerTag.version>ElementTag

Returns the client release version name (such as "1.21.1" or "26.2") of this online player.
Append .protocol (as in <PlayerTag.version.protocol>) to return the numeric protocol version ID instead (e.g. 767).

Mechanisms

show_dialogInput: ElementTag

Shows a specific dialog to the online player using the exact name of a Dialog script container.

close_dialogInput: None

Closes any currently open dialog for the online player.

UtilTag

Utility tags and extensions provided by Denizen Utilities.

Tags

<util.client_version_by_address[<address>]> ElementTag

Returns the raw client release version name (such as "1.21.1" or "26.2") for the specified IP address.
Append .protocol to return the numeric protocol version ID instead (e.g. 767).

Server List Ping & ViaVersion Bypass:
This tag is specifically designed for the on server list ping event.

When using ViaVersion, incoming handshake packets are rewritten to match the server core's version so the server accepts the ping. Because of this, Paper's <context.client_protocol_version> falsely reports the server core's version when a client connects with a newer version.

Example: On a 1.21.11 server with a 26.2 client, Paper reports 1.21.11. This tag resolves the genuine connection data directly, returning the true client version (26.2 / 776).

Example

server_ping_script:
  type: world
  events:
    on server list ping:
      - narrate "Paper: <context.client_protocol_version>"
      - narrate "Actual: <util.client_version_by_address[<context.address>].protocol>"

bmmodel

- bmmodel entity:<entity> model:<model> (remove)

Attaches a specific BetterModel to an entity or removes an existing one. An entity can have multiple models at once.

Pre-configuration Sub-block Support:
The bmmodel command supports passing a YAML sub-content block directly under the command to pre-configure mechanisms on model creation.
Note: Some mechanisms take effect only after animation playback, so using this pre-configuration feature is strongly recommended.

entity:Required

The target entity to attach or detach the model from.

model:Required

The model name (must exist in BetterModel's loaded models).

removeSwitch

If present, removes the model instead of adding it.

Example

- bmmodel entity:<context.entity> model:dragon
- bmmodel entity:<context.entity> model:dragon remove

- bmmodel entity:<player> model:dragon:
    glow: true
    glow_color: red
    model_scale: 1.5

bmlimb

- bmlimb target:<entity> model:<model> animation:<animation> (loop:<mode>) (override)

Manages BetterModel limb animations for a player.
Plays a specific limb animation for a player or NPC.

target:Required

The player or NPC target.

model:Required

The limb model name.

animation:Required

The animation name to play.

loop:Optional

Available loop modes: PLAY_ONCE, LOOP, HOLD_ON_LAST.

overrideSwitch

If present, overrides currently playing animations on this limb.

Example

- bmlimb target:<player> model:player_arm animation:wave loop:PLAY_ONCE

bmstate

- bmstate model:<BMActiveModelTag> (state:<animation>) (bones:<list>) (loop:<mode>) (speed:<#.#>) (override) (remove)

Starts, stops, or modifies animations on a model. Optionally targets specific bones.

model:Required

The BMActiveModelTag instance to target.

state:Optional*

The animation name. Required to start. Optional when stopping all animations via remove.

bones:Optional

List of bone names to target. Omit to affect all bones.

loop:Optional

Playback mode: PLAY_ONCE (default), LOOP, or HOLD_ON_LAST.

speed:Optional

Playback speed multiplier. Default: 1.0.

overrideSwitch

If present, forces the animation to override any currently running animations on the targeted bones.

removeSwitch

Stops the animation. No state given stops all animations.

Example

- bmstate model:<[my_model]> state:walk loop:LOOP speed:1.2
- bmstate model:<[my_model]> state:nod bones:head|waist loop:PLAY_ONCE
- bmstate model:<[my_model]> state:walk remove

bmpart

DEPRECATED

The bmpart command is now deprecated. Use BMBoneTag.skin / BMActiveModelTag.skin instead.

- bmpart entity:<entity> model:<model_name> bone:<bone> part:<limb_name> from:<player>

Applies a limb texture from an online player's skin to a specific bone. Useful for player-skin-based models.

entity:Required

The target entity holding the active model tracker.

model:Required

The active model tracker name operating on the entity.

bone:Required

The destination bone name in your model.

part:Required

Source limb name from the player skin (e.g. HEAD, TORSO).

from:Required

An online PlayerTag whose skin provides the texture source.

Example

- bmpart entity:<[some_npc]> model:statue bone:head part:HEAD from:<player>
- bmpart entity:<[some_npc]> model:chest_model bone:chest part:TORSO from:<player[PlayerName]>

bm start reload

on bm start reload:

Triggers when the BetterModel plugin begins the reload process (before models and resource packs are regenerated).

bm end reload

on bm end reload:

Triggers when the BetterModel plugin finishes reloading models and generating the resource pack.

<context.result>ElementTag

Returns the reload result details: SUCCESS, FAILURE, or RELOAD.

bm animation signal

on bm animation signal:

Triggers globally on the server when a BetterModel Blockbench animation keyframe is reached on the Instructions (Effects) track with a denizen: prefix.

Switches

name:<name>

Filter by the signal name argument to only run if matching.

Contexts

<context.name>ElementTag

Returns the basic name of the signal (e.g. 'strike' from denizen:strike{damage=5}).

<context.model>BMActiveModelTag

Returns the active model instance triggering the script keyframe.

<context.[key]>ElementTag

Returns custom parameter values defined inside the braces {} of the script line.

Blockbench Script Rules

Enter keyframes with: denizen:signal_name{arg1=val1;arg2=val2} on your animation instructions track.

Example

on bm animation signal name:strike:
  - narrate "Active model <context.model.name> applied <context.damage> points!"

Instruction Tracking Constraint

Currently in BetterModel, multiple script keys using identical prefixes on the Instructions track might fail to trigger sequentially (only the final key registers). To work around this constraint, place your script triggers on the Particle track in the "Script" options field, where keyframes execute sequentially without dropping events.

bm player animation signal

on bm player animation signal:

Triggers on the client-renderer level when an animation keyframe issues a personal visual trigger (using the built-in signal: prefix).

This event fires individually for every active player viewing the model at the keyframe's precise timeline moment.

Switches

name:<name>

Filters by the string value of the signal.

Contexts

<context.name>ElementTag

Returns the plain signal name (e.g. 'hit' from signal:hit).

Linked Player Context

The standard event player context <player> represents the individual viewing player who receives this visual indicator trigger.

bm player model interact

on bm player model interact:

Triggers when a player interacts (left or right clicks) with any hitbox belonging to an active BetterModel model.

Switches

name:<name>

Process only if the model's template blueprint name matches the specified pattern.

Contexts

<context.model>BMActiveModelTag

Returns the active model tracker instance that was interacted with.

<context.hand>ElementTag

Returns the hand used to perform the click action (e.g. MAIN_HAND or OFF_HAND).

Player Context

The standard player context <player> represents the online player who performed the interaction.

Example

on bm player model interact name:dragon:
  - narrate "You interacted with the dragon model using your <context.hand>!"

BMActiveModelTag

Prefix: bmactivemodel@. Represents an active tracker instance currently spawned and displaying in the game world.

Format: bmactivemodel@<entity_uuid>/<model_name>

Tags

<BMActiveModelTag.entity>EntityTag

Returns the underlying Bukkit entity that this active model tracker is attached to.

<BMActiveModelTag.name>ElementTag

Returns the name identification string of this model tracker instance.

<BMActiveModelTag.type>ElementTag

Returns the type of the model template. Possible values: PLAYER (for player limb/skin-based models) or GENERAL (for standard models).

<BMActiveModelTag.bone[<name>]>BMBoneTag

Returns the specific bone tag object matching the query name.

<BMActiveModelTag.bones>MapTag

Returns a map grouping all structural bones inside this tracker (mapped by bone name to BMBoneTag).

<BMActiveModelTag.running_animation>ElementTag

Returns the animation name currently running. Append .type to retrieve the loop playback mode (e.g. play_once, loop, hold_on_last).

<BMActiveModelTag.animations>ListTag(ElementTag)

Returns a list of all animations configured for this active instance model.

<BMActiveModelTag.animation_duration[<name>]>DurationTag

Returns the total duration value of the designated animation.

<BMActiveModelTag.viewers>ListTag(PlayerTag)

Returns a list of online players who are currently actively rendering/viewing the model tracker.

Mechanisms

Block 1: Global / Model-Level Mechanisms
These mechanisms operate natively on the model tracker as a single unified structure. They rotate, scale, or modify the entire model as a whole.

model_scaleDecimal

Applies a uniform global size multiplier to the entire model proportionally, preserving relative bone geometry and pivot points.

model_rotationQuaternionTag

Rotates the entire model as a single object (unlike rotation which turns each bone separately around its own center).

billboardElementTag

Globally sets the billboard mode for the model tracker (CENTER, VERTICAL, HORIZONTAL).

view_rangeDecimal

Globally sets the rendering view range for the model.

brightnessMapTag

Globally overrides the display entity brightness. Format: MapTag with block and sky keys (0-15).

glowBoolean

Globally toggles glowing effect on the entire model.

glow_colorColorTag

Globally sets the glow color for the model.

tintColorTag

Globally sets tint color for all bones in the model.

visibleBoolean

Globally toggles visibility of the entire model.

skinElementTag

Changes the skin of the active model to the player skin associated with the specified UUID or PlayerTag. Preserves bone scale, position, and translation transforms.

hide_fromListTag(PlayerTag)

Hides the entire model from the specified list of players.

show_toListTag(PlayerTag)

Makes the model visible again to the specified list of players.

force_updateNone

Manually forces a full synchronization update (bones, metadata, and hitboxes).

Block 2: Bulk Per-Bone Convenience Mechanisms
These mechanisms are provided for convenience. Under the hood, they iterate over every individual bone in the model and apply a flat parameter override to each bone.

itemItemTag

Overrides the item display on every individual bone in the model.

scaleLocationTag

Applies a flat scale vector (XYZ) override to every individual bone in the model. Note: For proportional model resizing, use model_scale in Block 1 instead.

translationLocationTag

Applies a flat translation vector (XYZ) override to every individual bone in the model.

rotationQuaternionTag

Applies a local rotation modifier to every individual bone in the model.

BMModelTag

Prefix: bmmodel@. Represents a model blueprint allowing retrieval of its data without creating an object in the world.

Format: bmmodel@<template_name>

Base Tag

<model[<name>]>BMModelTag

Returns the blueprint.

Tags

<BMModelTag.name>ElementTag

Returns the name of the model template.

<BMModelTag.type>ElementTag

Returns the model template type. Possible values: PLAYER (for player limb/skin-based models) or GENERAL (for standard models).

<BMModelTag.animations>ListTag(ElementTag)

Returns a list of all raw animation timeline names loaded for this file template.

<BMModelTag.animation_duration[<name>]>DurationTag

Returns the total duration value of the designated blueprint animation.

BMBoneTag

Prefix: bmbone@. Represents a specific bone within an active model.

Format: bmbone@<entity_uuid>/<model_name>/<bone_name>

Tags

<BMBoneTag.name>ElementTag

The name of the bone.

<BMBoneTag.location>LocationTag

Current world location of the bone (entity + relative offset).

<BMBoneTag.euler>LocationTag

Returns the rotation of the bone as Euler angles.

<BMBoneTag.passengers>ListTag(EntityTag)

List of entities mounted on this bone's seat.

<BMBoneTag.item>ItemTag

Returns the ItemTag currently displayed on this bone.

Mechanisms

billboardElementTag

Sets billboard mode for the bone.

view_rangeDecimal

Sets the view range for this bone.

brightnessElementTag

Overrides the brightness for this specific bone. Format: block_light,sky_light (e.g., 15,15).

glowBoolean

Sets whether the bone should glow.

glow_colorColorTag

Sets the glow color for the bone.

tintColorTag

Sets the tint color for the bone.

visibleBoolean

Sets whether the bone is visible.

skinElementTag

Changes the skin of the specified bone to the player skin associated with the specified UUID or PlayerTag. This is especially useful when working with limb models.

rotationQuaternionTag

Sets a custom rotation modifier for the bone.

mountEntityTag

Mounts an entity onto this bone (must have a seat).

dismountEntityTag

Dismounts a specific entity from this bone.

dismount_allNone

Dismounts all entities from this bone.

itemItemTag

Changes the item display of this bone.

scaleLocationTag

Sets the scale of the bone's item.

translationLocationTag

Sets the translation of the bone's item.

PlayerTag (Extensions)

Tags injected into standard Player objects by the BetterModel bridge.

<PlayerTag.limb>BMActiveModelTag

Returns the player's active player-renderer limb tracker.

EntityTag (Extensions)

Tags injected into standard Entity objects by the BetterModel bridge.

<EntityTag.model[(<name>)]>BMActiveModelTag

Returns the BetterModel active tracker model with the specified name from the entity. If no name is provided, returns the first active model.

<EntityTag.models>ListTag

Returns a list of all active BetterModel model names currently operating on the entity.

skin

Changes the skin of the specified player(s).

- skin [<name>/<url>/<texture>] (<player>|...)

If no targets are specified positionally, the player attached to the script queue will be used.

1. sourceRequired

A player name, an http URL, or raw texture data in value;signature format.

2. targetsOptional

One or more PlayerTag objects passed as a positional argument.

Example

- skin Notch
- skin https://minesk.in/7db... <[some_player]>
- skin <player.skin_blob> <server.online_players>

player skin apply

on player skin apply:

Triggers when a player's skin is being applied via SkinsRestorer.

Contexts

<context.value>ElementTag

The Base64 texture value of the skin being applied.

Determinations

TEXTURE:<val>;<sig>Determine

Override with raw texture data in value;signature format.

NAME:<name>Determine

Override with a skin fetched by player name.

URL:<url>Determine

Override with a skin fetched from a URL.

PlayerTag (Extensions)

Tags injected into standard Player objects by the SkinsRestorer bridge.

<PlayerTag.skin_url>ElementTag

Returns the URL of the player's current skin texture.

<PlayerTag.skin_type>ElementTag

Returns the skin type. Possible values: CUSTOM, LEGACY, PLAYER, or URL.

player links discord account

on player links discord account:

Triggers when a Minecraft player successfully links their Discord account.

<context.discord_id>ElementTag

Returns the Discord snowflake ID of the account that was linked.

player unlinks discord account

on player unlinks discord account:

Triggers when a Minecraft player unlinks their Discord account.

<context.discord_id>ElementTag

Returns the Discord snowflake ID of the account that was unlinked.

PlayerTag (Extensions)

Tags injected into standard Player objects by the DiscordSRV bridge.

<PlayerTag.discord_id>ElementTag

Returns the Discord snowflake ID associated with the Minecraft player's account via DiscordSRV. Returns null if the player has not linked their Discord account.