# Content Component (Body)
`Body` The node is used to display various content in the main menu area, such as plain text messages and item displays.
***
## Configuration Structure
```yaml
Body:
Component Name:
type: 'component type'
# Component-specific configuration...
```
* **Component Name**: Any string used as the unique identifier for this component (cannot be duplicated within the same menu)
* **Component Order**: Displayed in the order written in the YAML file, from top to bottom
***
## Component Type
### message - Plain Text Message
Display one or more lines of plain text messages in the menu.
**Configuration Items:**
| Field | Type | Description |
| ------- | --------------- | ----------------------------------------------------------------------------- |
| `type` | `String` | Fixed value `message` |
| `text` | `String`/`List` | Message text, supports multiple formats (see description below) |
| `width` | `Int` | Optional, message width (1-1024); if not set, the default width (200) is used |
***
### Text Format Support
KaMenu supports **MiniMessage API** and **Legacy color codes** two text formats, which can be freely chosen or mixed.
**Supported formats:**
1. **Legacy color codes**:`&a green text`、`&c red text`、`&6 gold text`
2. **MiniMessage format**:`green text`、`red text`、`gold text`
**Automatic detection mechanism:**
* The system will automatically detect whether the text contains MiniMessage tags (`<...>`)
* If MiniMessage tags are detected, MiniMessage parsing will be used
* If no MiniMessage tags are detected, Legacy color code parsing will be used
* The two formats can be mixed, and the system will handle them automatically
**Example:**
```yaml
# Using Legacy color codes
text: '&aWelcome to the server'
# Using MiniMessage format
text: 'Welcome to the server'
# Mixed use
text: '&aGreen text gold text'
```
**MiniMessage advantages:**
* A more modern text format that supports more styles (bold, italic, underline, etc.)
* Clearer tag structure, easier to maintain
* Fully compatible with the Adventure API
***
### Multiple formats for the text field
`text` The field supports three formats, suitable for different scenarios:
#### 1. Single-line text (supports \n line breaks)
The simplest format, using `\n` characters for line breaks.
```yaml
Body:
welcome_msg:
type: 'message'
text: '&7Welcome to the server shop\n&7Click the button below to browse items'
```
**Features:**
* Suitable for static multi-line text
* Supports `\n` line breaks
* Automatically parses variables and color codes
#### 2. List mode (one element per line)
Use a YAML list, one string per line.
```yaml
Body:
welcome_msg:
type: 'message'
text:
- '&7Welcome to the server shop'
- '&7Click the button below to browse items'
- '&7Happy shopping!'
```
**Features:**
* Clearer configuration format
* Each line managed independently
* Supports editing long text
* Automatically parses variables and color codes for each line
#### 3. Conditional mode (supports allow/deny branches)
Display different text content based on conditions. The allow and deny branches support two formats:
**Format A: List mode**
```yaml
Body:
status_msg:
type: 'message'
text:
- condition: '%player_is_op% == true'
allow:
- '&a✔ Current status: Administrator'
- '&7You have all permissions'
deny:
- '&7Current status: Regular player'
- '&7Please contact an administrator for an upgrade'
```
**Format B: String mode (supports \n line breaks)**
```yaml
Body:
status_msg:
type: 'message'
text:
- condition: '%player_is_op% == true'
allow: '&a✔ Current status: Administrator\n&7You have all permissions'
deny: '&7Current status: Regular player\n&7Please contact an administrator for an upgrade'
```
**Format A vs Format B comparison:**
| Feature | List mode (A) | String mode (B) |
| -------------------- | ----------------------------------- | ----------------------------------------------- |
| Readability | ✅ Clearer, each line is independent | ⚠️ Requires \n separators |
| Variable parsing | ✅ Parsed independently per line | ✅ Entire text parsed at once |
| Applicable scenarios | Multi-line, formatted text | Short text or text requiring logical connection |
**Features:**
* Dynamically display content based on conditions
* Both the allow/deny branches support list and string formats
* In list mode, each line is processed and variable parsing is done independently
* Both list mode and string mode are supported `\n` line breaks
* Supports nested conditional checks
* The two formats can be mixed (one using a list, one using a string)
***
### Advanced Example
**Multi-line + variables + colors:**
```yaml
Body:
player_info:
type: 'message'
text:
- '&aPlayer Name: &f{player_name}'
- '&aPlayer Balance: &e%vault_eco_balance% &7coins'
- '&aOnline Time: &e%player_time_played%'
- '&aServer Name: &f{gdata:server_name}'
```
**Multi-line + clickable text:**
```yaml
Body:
welcome_msg:
type: 'message'
text:
- '&7Welcome to the server!'
- '&7Please click the button below to continue'
- '&e'
```
**Conditional multi-line text (list mode):**
```yaml
Body:
vip_status:
type: 'message'
text:
- condition: '%vault_rank% == VIP'
allow:
- '&a✓ You are a valued VIP member'
- '&7Expiration time: &e%player_vip_expiry%'
- '&7Enjoy all premium services'
deny:
- '&7You are not yet a VIP member'
- '&7Click the button below to upgrade'
- '&7Only &e10 &7coins/month'
```
**Conditional multi-line text (\n line-break mode):**
```yaml
Body:
vip_status:
type: 'message'
text:
- condition: '%vault_rank% == VIP'
allow: '&a✓ You are a valued VIP member\n&7Expiration time: &e%player_vip_expiry%\n&7Enjoy all premium services'
deny: '&7You are not yet a VIP member\n&7Click the button below to upgrade\n&7Only &e10 &7coins/month'
```
**Mixed mode (allow uses list, deny uses string):**
```yaml
Body:
mixed_format:
type: 'message'
text:
- condition: '%player_is_op% == true'
allow:
- '&6[ Administrator Panel ]'
- '&7You have full access'
- '&7You can view all features'
deny: '&7[ Regular User Panel ]\n&7You can only access basic features\n&7Please contact an administrator for more permissions'
```
**Nested conditions:**
```yaml
Body:
player_type:
type: 'message'
text:
- condition: '%player_is_op% == true'
allow:
- condition: '%player_name% == AdminPlayer'
allow: '&6Server Administrator'
deny: '&6Administrator Account'
deny:
- condition: '%vault_rank% == VIP'
allow: '&aVIP player'
deny: '&7Regular player'
```
***
### Complete Example
**Basic example:**
```yaml
Body:
welcome_msg:
type: 'message'
text: '&7Welcome to the server shop, click the button below to browse items.'
separator:
type: 'message'
text: '&8————————————————'
```
**Custom width example:**
```yaml
Body:
wide_message:
type: 'message'
text: '&7This is a message with a width of 300'
width: 300
normal_message:
type: 'message'
text: '&7This is a message using the default width'
```
**Conditional width example:**
```yaml
Body:
dynamic_width:
type: 'message'
text: '&7Message content'
width:
- condition: "%player_is_op% == true"
allow: 400
deny: 200
```
**Interactive text example (using hovertext syntax):**
```yaml
Body:
# Single clickable link
simple_link:
type: 'message'
text: ''
# Clickable text with command
command_link:
type: 'message'
text: ''
# Mixed plain text and clickable text
mixed_text:
type: 'message'
text: '&7Welcome to the server! Visit for more information.'
# Multiple clickable areas
multi_link:
type: 'message'
text: '&7Feature navigation: '
# Conditional check + clickable text
conditional_click:
type: 'message'
text:
- condition: '%player_is_op% == true'
allow: ''
deny: ''
```
**hovertext syntax format:**
```
```
**Parameter description:**
| Parameter | Description | Required |
| --------- | ------------------------------------------------------------------- | -------- |
| `text` | Clickable display text | ✅ |
| `hover` | Tooltip text displayed on mouse hover | ❌ |
| `command` | The command executed by the player when clicked | ❌ |
| `url` | The website link opened when clicked | ❌ |
| `actions` | The action list executed when clicked (key name under Events.Click) | ❌ |
| `newline` | Whether to add a line break after the text (`true`/`false`) | ❌ |
**Notes:**
* `command` Commands in the... will be executed as the player (no need for the `/` prefix)
* `url` Used to open web links
* `actions` Used to execute action lists defined under Events.Click
* Clickable areas are wrapped with `< >` 包裹
* Parameter values can use backticks `` ` ``single quotes `'` or double quotes `"` 包裹
* Plain text and clickable text can be mixed
* Supports color codes and PAPI variables
* All fields support conditional checks
**Click event priority:**
When multiple click parameters exist at the same time, the priority is as follows (from high to low):
1. `actions` - Execute action list
2. `url` - Open link
3. `command` - Execute command
**Example using the actions parameter:**
```yaml
Events:
Click:
greet:
- 'tell: &aHello! Welcome to the server.'
- 'sound: ENTITY_PLAYER_LEVELUP'
Body:
welcome_msg:
type: 'message'
text: ' or view '
```
**Use cases:**
* **Button reuses action list**: multiple texts execute the same action sequence
* **Conditional branches**: execute different actions based on player status
* **Inline actions**: no separate definition needed, directly reference the action list under Events.Click
* **Mixing links and actions**: text containing both links and actions
***
### item - Item Display
Display an item icon in the menu, with optional name, lore, and description text.
**Configuration Items:**
| Field | Type | Required | Default Value | Description |
| ------------------- | -------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `String` | ✅ | — | Fixed value `item` |
| `material` | `String` | ✅ | `PAPER` | Item material name (supports multiple formats, see description below) |
| `amount` | `Int` | ❌ | `1` | Item stack amount (1-64); if not set, defaults to 1 |
| `name` | `String` | ❌ | Default item name | Item display name, supports color codes |
| `lore` | `List` | ❌ | — | Item lore (list of description text) |
| `description` | `String` | ❌ | — | Additional descriptive text displayed below the item, supports color codes, PAPI variables, conditional checks, and clickable text syntax |
| `description_width` | `Int` | ❌ | `0` | Width of the description text box (1-1024, pixels); if not set or set to 0, the default value 200 is used |
| `item_model` | `String` | ❌ | — | Item model identifier (format:`namespace:key`) used to display special material items (such as namespace item models in 1.21.7+) |
| `width` | `Int` | ❌ | `16` | Width of the item icon (pixels) |
| `height` | `Int` | ❌ | `16` | Height of the item icon (pixels) |
| `show_overlays` | `Boolean` | ❌ | `true` | Whether to show item overlays (durability bar, cooldown, amount, etc.) |
| `show_tooltip` | `Boolean` | ❌ | `true` | Whether to show the item tooltip when hovering the mouse |
**Example:**
```yaml
Body:
featured_item:
type: 'item'
material: 'ENCHANTED_BOOK'
name: '&6&lSacred Sword'
lore:
- '&7A legendary weapon'
- '&cAttack Power: &f+20'
- '&ePrice: &f500 coins'
description: '&fClick the button below to purchase this weapon'
width: 16
height: 16
# Item with custom description width
custom_width_item:
type: 'item'
material: 'DIAMOND'
name: '&b&lDiamond'
description: '&7This is a rare diamond\n&7Worth 1000 coins'
description_width: 200 # Custom description width
width: 16
height: 16
# Hide overlays (durability bar, amount, cooldown, etc.)
no_overlays_item:
type: 'item'
material: 'DIAMOND_SWORD'
name: '&6&lLegendary Sword'
show_overlays: false # Do not show durability bar, amount, or other overlays
width: 16
height: 16
# Item with custom amount
custom_item:
type: 'item'
material: 'DIAMOND'
name: '&b&lDiamond'
amount: 16 # Set stack amount to 16
width: 16
height: 16
```
**Description of the amount property:**
`amount` This property is used to set the item stack amount; the default value is `1`.
* **Value range**: 1-64 (depending on the item''s maximum stack size)
* **Applicable scenarios**:
* Display item stack count in the shop
* Display item quantity in inventory preview
* Display multiple items in equipment display
* **Usage examples:**
**Example 1: Single item**
```yaml
single_item:
type: 'item'
material: 'DIAMOND_SWORD'
name: '&6Diamond Sword'
amount: 1 # Single item (default value)
width: 16
height: 16
```
**Example 2: Stacked item**
```yaml
stack_item:
type: 'item'
material: 'DIAMOND'
name: '&bDiamond'
amount: 64 # Maximum stack size
width: 16
height: 16
```
**Example 3: Condition-controlled quantity**
```yaml
vip_item:
type: 'item'
material: 'GOLD_INGOT'
name: '&eGold Ingot'
amount:
- condition: '%vault_rank% == VIP'
allow: 32 # VIP players see 32
deny: 16 # Regular players see 16
width: 16
height: 16
```
**Example 4: Show quantity when show\_overlays: false**
```yaml
# When show_overlays: false, the stack amount will be hidden
# You can write the amount in the name property to display it on the interface
item_with_amount:
type: 'item'
material: 'DIAMOND'
name: '&bDiamond x64' # Display the quantity in the name
amount: 64 # Set the actual quantity (but do not display it on the icon)
show_overlays: false # Disable overlays; the amount will be hidden
width: 16
height: 16
```
* **Notes**:
* If the set value exceeds the item''s maximum stack size, it will automatically be limited to the maximum
* For non-stackable items such as tools and weapons, the amount will be limited to 1
* In slot reference mode, the`amount` property does not take effect (displays the actual number of items in the slot)
* **Important**: When `show_overlays: false` the item stack amount (such as "64") will be hidden and not displayed on the item icon. If you need to display the amount on the interface, it is recommended to write the amount in the `name` property, for example `name: '&bDiamond x64'`
**The name property is optional:**
* `name` This property is optional. If not provided, the item's default name will be used.
**The description\_width property is optional:**
* `description_width` This property is optional and is used to set the width of the description text (in pixels). If not set or set to 0, the default width 200 is used.
```yaml
Body:
# Use the item''s default name
diamond_sword:
type: 'item'
material: 'DIAMOND_SWORD'
# Do not set name, display the item''s default name "Diamond Sword"
width: 16
height: 16
# Custom item name
custom_sword:
type: 'item'
material: 'DIAMOND_SWORD'
name: '&6&lLegendary Sword' # Override the default name
width: 16
height: 16
# Use description_width to set the width
wide_description_item:
type: 'item'
material: 'ENCHANTED_BOOK'
name: '&6Magic Book'
description: '&7This is a magical book\n&7It can cast powerful spells'
description_width: 300 # Set the description width to 300 pixels
width: 16
height: 16
# Both description and description_width support conditional checks
conditional_description_item:
type: 'item'
material: 'DIAMOND'
name: '&bDiamond'
description:
- condition: '%player_level% >= 10'
allow: '&aAdvanced item\n&7You have unlocked purchasing permissions'
deny: '&7You need to reach &e10 &7level to purchase'
description_width:
- condition: '%player_level% >= 10'
allow: 300
deny: 200
width: 16
height: 16
```
{% hint style="info" %}
If the `name` property is not provided, the system will use the default Chinese name corresponding to the item material. If you need a custom display name, then set the `name` property.
{% endhint %}
**Supported item material name formats:**
KaMenu supports multiple material name formats, and the system will automatically normalize and match the corresponding Material enum:
* Standard format:`DIAMOND_SWORD`
* Lowercase:`diamond_sword`
* Mixed case:`DiAMond swORd`
* Hyphen:`Diamond-Sword`
* Space:`diamond sword`
* Underscore:`diamond_sword`
**Example:**
```yaml
# All of the following formats can match DIAMOND_SWORD
material: 'diamond_sword'
material: 'Diamond_Sword'
material: 'Diamond-Sword'
material: 'diamond sword'
material: 'diAMond swORd'
```
{% hint style="info" %}
The system will automatically ignore case, replace hyphens and spaces with underscores, and merge extra underscores, so all of the above formats will match correctly to `DIAMOND_SWORD`.
{% endhint %}
***
### Item Slot Reference
`material` The field supports slot reference format and can directly display the item in the player's equipment slot.
**Format:**
`[SLOT]` or `[SLOT:PlayerName]` or `[SLOT:{variable}]`
**Supported slots:**
| Slot name | Description | Corresponding Bukkit constant |
| ---------- | ------------------ | ----------------------------- |
| `HEAD` | Head (helmet) | `EquipmentSlot.HEAD` |
| `CHEST` | Chest (chestplate) | `EquipmentSlot.CHEST` |
| `LEGGINGS` | Leggings | `EquipmentSlot.LEGS` |
| `BOOTS` | Boots | `EquipmentSlot.FEET` |
| `MAINHAND` | Main hand | `EquipmentSlot.HAND` |
| `OFFHAND` | Off hand | `EquipmentSlot.OFF_HAND` |
**Basic example:**
```yaml
Body:
# Display the current player's helmet
player_helmet:
type: 'item'
material: '[HEAD]'
width: 16
height: 16
# Display a specified player's helmet
admin_helmet:
type: 'item'
material: '[HEAD:AdminPlayer]'
width: 16
height: 16
```
**Used with variables:**
Slot references support all variable types (PAPI variables, built-in variables, Meta variables, etc.):
```yaml
Body:
# Use Meta variables (with the player-click listener)
target_helmet:
type: 'item'
material: '[HEAD:{meta:player}]'
width: 16
height: 16
# Use data storage variables
saved_player_helmet:
type: 'item'
material: '[CHEST:{data:target_player}]'
width: 16
height: 16
# Use PAPI variables
random_player_sword:
type: 'item'
material: '[MAINHAND:%random_online_player%]'
width: 16
height: 16
```
**Empty slot handling:**
When the referenced slot is empty, the system will automatically display a replacement item:
| Slot | Empty slot display |
| ----------- | ------------------------------------------ |
| `HEAD` | Player skin head |
| Other slots | Light gray stained glass pane named "None" |
```yaml
Body:
# Display a player head when the head slot is empty
helmet_display:
type: 'item'
material: '[HEAD:{meta:player}]'
width: 16
height: 16
# Display a light gray stained glass pane when other slots are empty
chestplate_display:
type: 'item'
material: '[CHEST:{meta:player}]'
width: 16
height: 16
```
**Full example - player interaction menu:**
```yaml
# menus/inspect_player.yml
Title: 'Player Info'
Background: '#1a1a1a'
Body:
# Display the player's helmet
helmet:
type: 'item'
material: '[HEAD:{meta:player}]'
description: '&7View head equipment'
width: 16
height: 16
# Display the player's chestplate
chestplate:
type: 'item'
material: '[CHEST:{meta:player}]'
description: '&7View chest equipment'
width: 16
height: 16
# Display the player's leggings
leggings:
type: 'item'
material: '[LEGGINGS:{meta:player}]'
description: '&7View leg equipment'
width: 16
height: 16
# Display the player's boots
boots:
type: 'item'
material: '[BOOTS:{meta:player}]'
description: '&7View foot equipment'
width: 16
height: 16
Events:
Click:
# Use slot references to display target player equipment
```
{% hint style="info" %}
In slot reference mode, use `description` the property to add descriptive text instead of using `name` the property, because `name` the property does not take effect when the slot has an item.
{% endhint %}
**With the player-click listener:**
```yaml
# config.yml
listeners:
player-click:
enabled: true
menu: 'inspect_player'
require-sneaking: false
```
When a player right-clicks another player:
1. The system automatically sets `{meta:player}` to the clicked player's name
2. Open `inspect_player` menu
3. In the menu, `[HEAD:{meta:player}]` and similar references will display the clicked player's equipment
**Notes:**
1. **The following properties do not work in slot reference mode:**
* `name`(except empty slots)
* `amount`
* `lore`
* `item_model`
About name properties:
- When a slot has an item, use the item's own name,
name the property does not take effect - When the slot is empty, the HEAD slot displays a player head (using the player's name), and other slots display a light gray stained glass pane (name fixed as "None"),
name the property does not take effect - If you need a custom name, you can add descriptive text in
description to