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

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.

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

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

Contexts

<context.connection>

Returns the ConnectionTag associated with the joining player.

Determinations

WAITDetermine

Delays the configuration process for up to 1 minute. During this time, you can show Dialogs or process backend tasks. If not finished manually via connect mechanism within 1 minute, the connection will be dropped.

BiomeTag

Additions for interacting with Biomes.

Tags

<BiomeTag.sky_color>

Returns the ColorTag of the biome's sky color.

<BiomeTag.sky_light_color>

Returns the ColorTag of the biome's skylight color.

Mechanisms

sky_colorInput: ColorTag

Sets the biome's sky color permanently.

sky_light_colorInput: ColorTag

Sets the biome's skylight color permanently.

ConnectionTag

Methods and properties for interacting with client connections.

Tags

<ConnectionTag.uuid>

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

<ConnectionTag.name>

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

Mechanisms

connectInput: None

Confirms the connection and allows the player to continue the login process.

disconnectInput: ElementTag

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

show_dialogInput: ElementTag

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.

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.

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.

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.

Usage

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

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.

Usage

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

Usage

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

Usage

- 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. (e.g. <context.damage> for the argument denizen:strike{damage=5}).

Blockbench Script Rules

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

Example usage

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 usage

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

billboardElementTag

Globally sets the billboard mode for all bones in the model (e.g. CENTER, VERTICAL, HORIZONTAL).

view_rangeDecimal

Globally sets the view range for all bones in this model.

brightnessElementTag

Globally overrides the brightness for all bones. Format: block_light,sky_light (e.g., 15,15).

glowBoolean

Globally toggles glow on the entire model.

glow_colorColorTag

Globally sets glow color for all bones.

tintColorTag

Globally sets tint color for all bones.

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. This is especially useful when working with limb models.

itemItemTag

Globally overrides the item displayed on all bones.

scaleLocationTag

Globally overrides the scale for all bones (XYZ vector format).

model_scaleDecimal

Applies a uniform global size multiplier to the entire model proportionally.

translationLocationTag

Globally overrides translation vectors for all model bones.

rotationQuaternionTag

Globally sets a custom rotation modifier for all bones.

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.

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.

Usage

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