### Example command to get CustomModelData

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/holographic-displays

Example command to get CustomModelData for the 'ruby' item.

```text
/iacustommodeldata ruby
```

--------------------------------

### item_display furniture example with lava lamp

Source: https://wiki.itemsadder.com/adding-content/furnitures

Complete example of a furniture item (lava_lamp_new) using item_display entity, with light level and display transformation.

```yaml
  lava_lamp_new:
    enabled: true
    display_name: display-name-lava_lamp
    permission: iadeco.decorations.lava_lamp
    lore:
      - lore-decorative-item
    resource:
      material: PAPER
      generate: false
      model_path: lava_lamp
    behaviours:
      furniture:
        entity: item_display # <---
        light_level: 7
        display_transformation:
          transform: HEAD
          right_rotation:
            axis_angle:
              angle: 180
              axis:
                x: 0
                y: 1
                z: 0
          translation:
            x: 0
            y: 0.92
            z: 0
          scale:
            x: 0.45
            y: 0.45
            z: 0.45
```

--------------------------------

### ItemBridge give example

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/itembridge

Example of giving the ItemsAdder item 'itemsadder:ruby_sword' to player 'LoneDev'. The 'ia:' prefix is required for ItemBridge to recognize the item.

```text
/ib give LoneDev ia:itemsadder:ruby_sword
```

--------------------------------

### Full furniture configuration example

Source: https://wiki.itemsadder.com/adding-content/furnitures/example

A complete configuration block for the lamp furniture item.

```yaml
info:
  namespace: myitems
items:
  lamp:
    display_name: "Lamp"
    permission: myitems.decorative.lamp
    lore:
    - lore-decorative-item
    resource:
      material: PAPER
      generate: false
      model_path: lamp
    behaviours:
      furniture:
        light_level: 13
        solid: true
        placeable_on:
          floor: true
          ceiling: false
          walls: false
        hitbox:
          height: 1
        sound:
          place:
            name: block.metal.fall
          break:
            name: block.metal.break
```

--------------------------------

### Example self-host configuration with custom IP

Source: https://wiki.itemsadder.com/plugin-usage/plugin-configuration/resourcepack-hosting/self-hosting

An example of the self-host configuration block using a specific server IP address.

```yaml
  self-host:
    enabled: true
    server-ip: '123.456.789.0'
    pack-port: 8163
```

--------------------------------

### YAML example of multiple actions of the same type

Source: https://wiki.itemsadder.com/adding-content/items/item-properties/actions

Shows how to define multiple actions of the same type by appending a suffix (e.g., _first, _second, _3) to the action name. This example plays three sounds.

```yaml
play_sound_first:
  name: itemsadder:ambient.creepy
  volume: 1
  pitch: 1
play_sound_second:
  name: minecraft:ambient.cave
  volume: 1
  pitch: 1
play_sound_3:
  name: minecraft:ambient.cave
  volume: 1
  pitch: 1
```

--------------------------------

### Example: Teleporter Script

Source: https://wiki.itemsadder.com/adding-content/scripting/jspp/examples

A complete example script that saves player coordinates and orientation in a held item and teleports the player when used, with a usage count.

```APIDOC
## Example: Teleporter Script

### Description
This script demonstrates the use of data utility methods to save and retrieve player coordinates and orientation in a held item, and to teleport the player when the item is used. It also tracks usage count and removes data when exhausted.

### Code
```java
// Test: Save or use player coordinates and orientation in held item, with usage count
let item = $itemStack;
let ns = "myplugin";
let keyX = "coord_x";
let keyY = "coord_y";
let keyZ = "coord_z";
let keyYaw = "coord_yaw";
let keyPitch = "coord_pitch";
let keyUses = "coord_uses";
let maxUses = 3; // Set how many times the item can be used

// Try to read already saved coordinates and orientation
let hasCoords = hasData(item, ns, keyX) && hasData(item, ns, keyY) && hasData(item, ns, keyZ) && hasData(item, ns, keyYaw) && hasData(item, ns, keyPitch);

if (!hasCoords) {
  // Save current coordinates and orientation in the item
  let loc = $player.getLocation();
  setDataDouble(item, ns, keyX, loc.getX());
  setDataDouble(item, ns, keyY, loc.getY());
  setDataDouble(item, ns, keyZ, loc.getZ());
  setDataFloat(item, ns, keyYaw, loc.getYaw());
  setDataFloat(item, ns, keyPitch, loc.getPitch());
  setDataInt(item, ns, keyUses, maxUses);

  // Verify writing
  let savedX = getDataDouble(item, ns, keyX, 0);
  let savedY = getDataDouble(item, ns, keyY, 0);
  let savedZ = getDataDouble(item, ns, keyZ, 0);
  let savedYaw = getDataFloat(item, ns, keyYaw, 0);
  let savedPitch = getDataFloat(item, ns, keyPitch, 0);
  let savedUses = getDataInt(item, ns, keyUses, 0);

  msg($player, "Saved coordinates: " + savedX + ", " + savedY + ", " + savedZ + " (Yaw: " + savedYaw + ", Pitch: " + savedPitch + ")");
  msg($player, "Usages left: " + savedUses);

  if (savedX != loc.getX() || savedY != loc.getY() || savedZ != loc.getZ() || savedYaw != loc.getYaw() || savedPitch != loc.getPitch()) {
    msg($player, "Test FAILED: saving coords/orientation");
  } else {
    msg($player, "Coordinates and orientation saved in the item.");
  }
} else {
  // Read and use the saved coordinates and orientation
  let x = getDataDouble(item, ns, keyX, 0);
  let y = getDataDouble(item, ns, keyY, 0);
  let z = getDataDouble(item, ns, keyZ, 0);
  let yaw = getDataFloat(item, ns, keyYaw, 0);
  let pitch = getDataFloat(item, ns, keyPitch, 0);
  let uses = getDataInt(item, ns, keyUses, 1);

  $player.teleport(new Location($player.getWorld(), x, y, z, yaw, pitch));
  msg($player, "Teleported to saved coordinates: " + x + ", " + y + ", " + z + " (Yaw: " + yaw + ", Pitch: " + pitch + ")");

  // Decrement usage count
  uses -= 1;
  if (uses > 0) {
    setDataInt(item, ns, keyUses, uses);
    msg($player, "Usages left: " + uses);
  } else {
    // Remove data and decrease item amount
    removeData(item, ns, keyX);
    removeData(item, ns, keyY);
    removeData(item, ns, keyZ);
    removeData(item, ns, keyYaw);
    removeData(item, ns, keyPitch);
    removeData(item, ns, keyUses);
    if (hasData(item, ns, keyX) || hasData(item, ns, keyY) || hasData(item, ns, keyZ) || hasData(item, ns, keyYaw) || hasData(item, ns, keyPitch) || hasData(item, ns, keyUses)) {
      msg($player, "Test FAILED: removeData");
    }
    // Decrease item amount
    item.setAmount(item.getAmount() - 1);
    msg($player, "No usages left, item amount decreased.");
  }
}
```
```

--------------------------------

### Get the custom bundle with /iaget

Source: https://wiki.itemsadder.com/adding-content/items/bundle

Use this command to obtain the custom bundle item in-game for testing.

```text
/iaget my_bundle_tutorial:ruby_bundle
```

--------------------------------

### defaultscoreboard.yml - Example YAML configuration

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/animatedscoreboard

A complete example YAML configuration file for a scoreboard with hidden background, using %img_offset_-500% on every line. It includes animated title, player info, and random color rotation lines.

```yaml
display:
    title:
      text:
      - "%img_offset_-500%&lA"
      - "%img_offset_-500%&lAn"
      - "%img_offset_-500%&lAni"
      - "%img_offset_-500%&lAnim"
      - "%img_offset_-500%&lAnima"
      - "%img_offset_-500%&lAnimat"
      - "%img_offset_-500%&lAnimate"
      - "%img_offset_-500%&lAnimated"
      - "%img_offset_-500%&lAnimated "
      - "%img_offset_-500%&lAnimated S"
      - "%img_offset_-500%&lAnimated Sc" 
      - "%img_offset_-500%&lAnimated Sco"
      - "%img_offset_-500%&lAnimated Scor"
      - "%img_offset_-500%&lAnimated Score"
      - "%img_offset_-500%&lAnimated Scoreb"
      - "%img_offset_-500%&lAnimated Scorebo"
      - "%img_offset_-500%&lAnimated Scoreboa"
      - "%img_offset_-500%&lAnimated Scoreboar"
      - "%img_offset_-500%&lAnimated Scoreboard"
      - "%img_offset_-500%&c&lAnimated Scoreboard"     
      - "%img_offset_-500%&lAnimated Scoreboard"
      - "%img_offset_-500%&c&lAnimated Scoreboard"
      - "%img_offset_-500%&lAnimated Scoreboard"
      - "%img_offset_-500%&c&lAnimated Scoreboard"
      - "<stay ticks=100>%img_offset_-500%&lAnimated Scoreboard</stay>"
      random: false
      interval: 2
    line-1:
      text:
      - "%img_offset_-500%"
      random: false
      interval: 200
      score: 99   
    line-2:
      text:
      - "%img_offset_-500%&a&lWelcome %player_name%"
      - "%img_offset_-500%&b&lWelcome %player_name%"
      - "%img_offset_-500%&c&lWelcome %player_name%"   
      random: false
      interval: 5
      score: 98
    line-3:
      text:
      - "%img_offset_-500%"
      random: false
      interval: 20
      score: 97
    line-4:
      text:
      - "%img_offset_-500%&aYour gamemode:"
      - "%img_offset_-500%&aYour location:"
      - "%img_offset_-500%&aYour world:"    
      random: false
      interval: 60
      score: 96
    line-5:
      text:
      - "%img_offset_-500% &b%player_gamemode%"
      random: false
      interval: 60
      score: 95
    line-6:
      text:
      - "%img_offset_-500% &bX:%player_x% Y:%player_y% Z:%player_z%"
      random: false
      interval: 1
      score: 95
    line-7:
      text:
      - "%img_offset_-500% &b%player_world%"    
      random: false
      interval: 60
      score: 95
    line-8:
      text:
      - "%img_offset_-500%"
      random: false
      interval: 200
      score: 95
    line-9:
      text:
      - "%img_offset_-500%&1Random Rotation"
      - "%img_offset_-500%&2Random Rotation"
      - "%img_offset_-500%&3Random Rotation"
      - "%img_offset_-500%&4Random Rotation"
      - "%img_offset_-500%&5Random Rotation"
      - "%img_offset_-500%&6Random Rotation"
      - "%img_offset_-500%&7Random Rotation"
      - "%img_offset_-500%&8Random Rotation"
      - "%img_offset_-500%&9Random Rotation"
      - "%img_offset_-500%&aRandom Rotation"
      - "%img_offset_-500%&bRandom Rotation"
      - "%img_offset_-500%&cRandom Rotation"
      - "%img_offset_-500%&dRandom Rotation"
      - "%img_offset_-500%&eRandom Rotation"
      - "%img_offset_-500%&kRandom Rotation" 
      - "%img_offset_-500%&lRandom Rotation" 
      - "%img_offset_-500%&mRandom Rotation" 
      - "%img_offset_-500%&nRandom Rotation"
      - "%img_offset_-500%&oRandom Rotation"
      - "%img_offset_-500%&rRandom Rotation"       
      random: true
      interval: 1
      score: 94
    line-10:
      text:
      - "%img_offset_-500%"       
      random: true
      interval: 1
      score: 93
```

--------------------------------

### YAML example of multiple behaviours

Source: https://wiki.itemsadder.com/adding-content/items/item-properties/behaviours

This YAML snippet shows how to configure various behaviours for an item, including trade machines, furniture, sitting, gun, hat, keep-on-death, music disc, and vehicle. Each behaviour is defined as a key with its specific properties. The example includes comments explaining optional settings and usage.

```yaml
# This behaviour allows you to open a trade GUI with the following items
# For example black_fishing_rod and red_fishing_rod
block_trade_machine:
  title: "Your title"
  permission: "mypermission.trade.example" # <--- this is optional
  gui_texture: ###THIS IS OPTIONAL, use it only to retexture the GUI
    left: customization_table_left
    right: customization_table_right
  trades_list:
    black_fishing_rod:
      ingredients:
        slot1:
          item: FISHING_ROD
          amount: 1
        slot2:
          item: BLACK_DYE
          amount: 1
      result:
        item: black_fishing_rod
        amount: 1
    red_fishing_rod:
      ingredients:
        slot1:
          item: FISHING_ROD
          amount: 1
        slot2:
          item: RED_DYE
          amount: 1
      result:
        item: red_fishing_rod
        amount: 1
        
furniture_trade_machine:
# ....... it's the same as block_trade_machine

   
# When you rightclick with that item it will be placed on the ground with an
# armorstand. The armorstand will have the item as helmet and will be invisible.
furniture:
  entity: armor_stand # you can also use item_frame (works better on 1.16+)
  small: true
  gravity: true
  fixed_rotation: false
  light_level: 7  
  solid: false
  opposite_direction: false #makes the model rotate 180 when placed
  hitbox:
    length: 2
    width: 2.3
    height: 1
    length_offset: 0.5
    width_offset: 0.5
    height_offset: 0.5
  placeable_on:
    walls: false
    ceiling: false
    floor: true

# If you add this behaviour and "furniture" behaviour you will be able to sit
# on the furniture at the defined height.
furniture_sit:
  sit_height: 0.9
  opposite_direction: true #default is true
  # Sit on every BARRIER block of the furniture (for multi-seats chairs)
  sit_all_solid_blocks: false
  

# Allows you to use this item as a gun. You can decide which projectile must
# be hold on left hand in order to shot.
gun:
  projectile: itemsadder:clip
  

# Allows you to use the current item as hat (same vanilla helmet behaviour)
hat: true

# Allows you to make the item stay in player inventory on death
keep_on_death: true

# Allows you to use the current item as a vanilla music disc.
# Remember that you will have to create a custom sound to be able
# to play something.
music_disc:
  song:
    name: "itemsadder:music_disc.cdk_sunday"
    description: "Cdk - Sunday"
    

# Allows you to use the current item as a ridable vehicle
vehicle:
  fixed_rotation: false
  small: true
  sit_height: 0
  step_height: 0.1
  hitbox:
    length: 2
    width: 1.7
    height: 1
  speed:
    drive: 1
    jump: 0.3
    fly: 0
  fuel:
    start: 150
    max: 300
    items:
      COAL: 1
      CHARCOAL: 1
      COAL_BLOCK: 9
      "itemsadder:banana": 1
  smoke:
    amount: 2
    offset:
      x: 0
      y: 0
      z: -0.8
```

--------------------------------

### Basic furniture configuration in furniture_example.yml

Source: https://wiki.itemsadder.com/adding-content/furnitures/example

Initial configuration for a lamp item using the furniture behavior.

```yaml
info:
  namespace: myitems
items:
  lamp:
    display_name: "Lamp"
    permission: myitems.decorative.lamp
    lore:
    - lore-decorative-item
    resource:
      material: PAPER
      generate: false
      model_path: lamp
    behaviours:
      furniture:
        light_level: 13
```

--------------------------------

### Adding a title to hover preview

Source: https://wiki.itemsadder.com/adding-content/font-images/emojis

Example of override_text with a title line before the big emoji, using \n to start a new line.

```yaml
override_text: "Emoji preview:\n:test_hover_new_big:\n\n\n\n\n\n"
```

--------------------------------

### Java ItemScript Example

Source: https://wiki.itemsadder.com/adding-content/scripting/java/examples

This script logs the custom item ID, sends a greeting to the player, gives a diamond, and attempts to give a ruby from the iasurvival pack if it is installed.

```java
package iascript;

import org.bukkit.event.Event;
import org.bukkit.plugin.Plugin;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import dev.lone.itemsadder.api.*;
import dev.lone.itemsadder.api.scriptinginternal.*;
import static dev.lone.itemsadder.api.scriptinginternal.ScriptingUtils.*;

public class example extends ItemScript {
  public void handleEvent(Plugin plugin, Event event, Player player, CustomStack $customStack, ItemStack $itemStack) {
    log("Player " + player.getName() + " interacted with item: " + $customStack.getNamespacedID());
    
    player.sendMessage("Hello from example script!");

    player.getInventory().addItem(new ItemStack(Material.DIAMOND, 1));
    player.sendMessage("You have been given a diamond!");

    var customStack = CustomStack.getInstance("iasurvival:ruby");
    if(customStack != null) {
      log("Custom stack found: " + customStack.getNamespacedID());
      player.getInventory().addItem(customStack.getItemStack());
      player.sendMessage("You have been given a ruby!");
    } else {
      log("Custom stack not installed on the server: iasurvival:ruby");
      player.sendMessage("Ruby item not found.");
    }
    
  }
}
```

--------------------------------

### Configure MythicMobs Equipment with ItemsAdder items

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/mythicmobs

Example showing how to equip a mob with custom ItemsAdder items in various equipment slots.

```yaml
SkeletalKnight:
  Type: WITHER_SKELETON
  Display: '&aSkeletal Knight'
  Health: 40
  Damage: 8
  Equipment:
  - myitems:special_helmet HEAD
  - myitems:special_chestplate CHEST
  - myitems:special_leggings LEGS
  - myitems:special_boots FEET
  - myitems:special_sword HAND
  - myitems:special_shield OFFHAND
```

--------------------------------

### Example configuration (YAML)

Source: https://wiki.itemsadder.com/adding-content/scripting/jspp/examples

YAML configuration defining an item with a script executor and a script reference. The script path points to a .jspp file.

```yaml
info:
  namespace: test
items:
  script_executor:
    name: script_executor
    resource:
      material: PAPER
      generate: false
      model_path: minecraft:item/diamond
    events:
      interact:
        left:
          script:
            name: test:script_test
scripts:
  script_test:
    path: script_test.jspp

```

--------------------------------

### Java script package declaration

Source: https://wiki.itemsadder.com/adding-content/scripting/java/debug

The script file must start with a package declaration that matches its folder path. For example, a file at ItemsAdder/contents/test/iascript/example.java must use package iascript;.

```java
package iascript;
```

--------------------------------

### Example configuration for red_zombie spawn

Source: https://wiki.itemsadder.com/adding-content/entities/entity-random-spawn

Configures a custom entity 'red_zombie' to spawn with a 20% chance when a vanilla zombie spawns, replacing it. It spawns only in worlds starting with 'world', between y=0 and 150, during RAIN weather, and with light level 0 to 10.

```yaml
info:
  namespace: test
entities:
  red_zombie:
    model_folder: entity/red_zombie
    can_sun_burn: false
    type: ZOMBIE
entities_populators:
  red_zombie_1:
    entity: test:red_zombie
    spawn_logic:
      method: REPLACE # or SPAWN_NEAR
      types:
      - ZOMBIE
    chance: 20.0
    amount: 1
    worlds:
    - world*
    # you can also use x and z as location_range parameters, for example
    # to make edge of the worlds harder with more dangerous mobs
    location_range:
      y:
        min: 0
        max: 150
    weather:
    - RAIN
    light_level:
      min: 0
      max: 10
```

--------------------------------

### Full Armor Configuration Example

Source: https://wiki.itemsadder.com/adding-content/items/armors

A complete configuration file including equipment definitions and multiple armor pieces.

```yaml
info:
  namespace: my_armor_tutorial
equipments:
  my_armor_1:
    type: armor
    layer_1: armor/my_armor_1/layer_1
    layer_2: armor/my_armor_1/layer_2
items:
  my_armor_1_helmet:
    name: My Armor 1 Helmet
    material: IRON_HELMET
    graphics:
      texture: item/my_armor_1_helmet
    durability:
      max_durability: 165
    equipment:
      id: my_armor_tutorial:my_armor_1
      slot_attribute_modifiers:
        armor: 2.5
  my_armor_1_chestplate:
    name: My Armor 1 Chestplate
    material: IRON_CHESTPLATE
    graphics:
      texture: item/my_armor_1_chestplate
    durability:
      max_durability: 165
    equipment:
      id: my_armor_tutorial:my_armor_1
      slot_attribute_modifiers:
        armor: 1
  my_armor_1_leggings:
    name: My Armor 1 Leggings
    material: IRON_LEGGINGS
    graphics:
      texture: item/my_armor_1_leggings
    durability:
      max_durability: 165
    equipment:
      id: my_armor_tutorial:my_armor_1
      slot_attribute_modifiers:
        armor: 2.5
  my_armor_1_boots:
    name: My Armor 1 Boots
    material: IRON_BOOTS
    graphics:
      texture: item/my_armor_1_boots
    durability:
      max_durability: 165
    equipment:
      id: my_armor_tutorial:my_armor_1
      slot_attribute_modifiers:
        armor: 2.5
```

--------------------------------

### Example placeholder with smile emoji

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/holographic-displays

Example of the placeholder with the 'smile' font image.

```text
%img_smile%
```

--------------------------------

### Get CustomModelData for an item

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/holographic-displays

Command to get the CustomModelData value for an item, e.g., 'ruby'.

```text
/iacustommodeldata <item>
```

--------------------------------

### Example using custom sounds

Source: https://wiki.itemsadder.com/adding-content/blocks

Configures block sounds using custom sound names from the 'my_sounds' namespace. Requires adding custom sounds to the resourcepack as described in the sounds tutorial.

```yaml
    sound:
      break:
        name: my_sounds:sound_1
      place:
        name: my_sounds:sound_2
      hit:
        name: my_sounds:sound_3
      step:
        name: my_sounds:sound_4
      fall:
        name: my_sounds:sound_5

```

--------------------------------

### Legacy color code inline example

Source: https://wiki.itemsadder.com/plugin-usage/beginners/text-formatting

Inline example of a legacy color code in a display_name field: '&6TEST'.

```yaml
display_name: '&6TEST'
```

--------------------------------

### Step 2: Create furniture item (furniture)

Source: https://wiki.itemsadder.com/adding-content/furnitures/furniture-2d-icon

Defines the furniture item that shows the placed model. It uses a non-generated PAPER with model_path 'decoration/furniture', has furniture behaviors (solid, cancel_drop, hitbox), and on break drops the 2d_furniture item. Also includes the 2d_furniture definition again.

```yaml
info:
  namespace: myitems
items:
  furniture:
    display_name: furniture
    permission: furniture
    lore:
    - 'lore-decorative-item'
    resource:
      material: PAPER
      generate: false
      model_path: decoration/furniture
    behaviours:
      furniture:
        solid: true
        cancel_drop: true
        hitbox:
          length: 1
          width: 1
          height: 1
    events:
      placed_armorstand:
        break:
          drop_item:
            item: 2d_furniture
  2d_furniture:
    display_name: 2d_furniture
    permission: 2d_furniture
    resource:
      material: PAPER
      generate: true
      textures:
      - item/2d_furniture
    events:
      interact:
        right:
          place_furniture:
            furniture: furniture
            decrement_amount: true
        right_shift:
          place_furniture:
            furniture: furniture
            decrement_amount: true
```

--------------------------------

### Java IllegalArgumentException log example

Source: https://wiki.itemsadder.com/faq/turkish-computer-errors

An example of the error message that occurs when the system locale interferes with Java symbol processing.

```log
java.lang.IllegalArgumentException: Symbol does not appear in the shape
```

--------------------------------

### Advanced furniture configuration with hitbox and sounds

Source: https://wiki.itemsadder.com/adding-content/furnitures/example

Extended configuration including placement rules, hitbox dimensions, and custom sounds.

```yaml
  lamp:
    display_name: "Lamp"
    permission: myitems.decorative.lamp
    lore:
    - lore-decorative-item
    resource:
      material: PAPER
      generate: false
      model_path: lamp
    behaviours:
      furniture:
        light_level: 13
        solid: true
        placeable_on:
          floor: true
          ceiling: false
          walls: false
        hitbox:
          height: 1
        sound:
          place:
            name: block.metal.fall
          break:
            name: block.metal.break
```

--------------------------------

### YAML example with delay attribute for commands and sounds

Source: https://wiki.itemsadder.com/adding-content/items/item-properties/actions

Shows a full item configuration with multiple actions (execute_commands and play_sound) each having a delay attribute in ticks. The delays are 0, 20, and 40 ticks, creating a sequence of actions.

```yaml
items:
  chain_events:
    display_name: "%#FE5A00%chain_events"
    permission: test.chain_events
    resource:
      material: COAL
      generate: true
      textures:
      - "minecraft:item/diamond.png"
    events:
      interact:
        right:
          execute_commands:
            cmd1:
              command: 'tellraw {player} {"text":"Action 1","color":"gold"}'
              as_console: true
              delay: 0
            cmd2:
              command: 'tellraw {player} {"text":"Action 2","color":"gold"}'
              as_console: true
              delay: 20
            cmd3:
              command: 'tellraw {player} {"text":"Action 3","color":"gold"}'
              as_console: true
              delay: 40
          play_sound_1:
            name: minecraft:block.note_block.banjo
            delay: 0
          play_sound_2:
            name: minecraft:block.note_block.banjo
            pitch: 1.2
            delay: 20
          play_sound_3:
            name: minecraft:block.note_block.banjo
            pitch: 1.5
            delay: 40
```

--------------------------------

### Model JSON texture reference example

Source: https://wiki.itemsadder.com/adding-content/blocks/entity-blocks

Example of how the model JSON must reference textures using the correct namespace.

```json
"my_entity_blocks:block/ruby_crate"
```

--------------------------------

### ItemBridge get command

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/itembridge

Command to get an ItemsAdder custom item using ItemBridge. The item namespaced id must be prefixed with 'ia:'.

```text
/ib get ia:<item namespaced id>
```

--------------------------------

### Example using vanilla sounds

Source: https://wiki.itemsadder.com/adding-content/blocks

Configures block sounds using vanilla Minecraft sound names. The block uses a REAL_NOTE placed model with PRISMARINE_BREAK particles and a whitelist for pickaxes.

```yaml
    behaviours:
      block:
        placed_model:
          type: REAL_NOTE
          break_particles_material: PRISMARINE_BRICKS
        break_tools_whitelist:
          - PICKAXE
          - pickaxe
        sound:
          break:
            name: minecraft:block.amethyst_block.break
          place:
            name: minecraft:block.amethyst_block.place
          hit:
            name: minecraft:block.amethyst_block.hit
          step:
            name: minecraft:block.amethyst_block.step
          fall:
            name: minecraft:block.amethyst_block.fall

```

--------------------------------

### Block utility functions

Source: https://wiki.itemsadder.com/adding-content/scripting/jspp/examples

Utility functions for block operations: check custom, get custom block, get block/location, remove/place blocks.

```java
isCustom(Block block);
customBlock(Block block);
customBlock(Location location);

block(String worldName, int x, int y, int z);
block(World world, int x, int y, int z);
block(Location location);

location(String worldName, int x, int y, int z);

removeBlock(Block block);
placeBlock(Block block, Material material);
placeBlock(Block block, CustomBlock customBlock);
placeBlock(Block block, String identifier);
```

--------------------------------

### Execute command with vanilla selector

Source: https://wiki.itemsadder.com/plugin-usage/plugin-configuration/commands/use-vanilla-selectors-in-commands

Example command syntax using PsudoCommands to enable vanilla selector support in an ItemsAdder entity summon command.

```text
/execute at (player) run psudo iaentity summon (entity) ~ ~ ~ world
```

--------------------------------

### VSCode launch.json for attaching to server

Source: https://wiki.itemsadder.com/adding-content/scripting/java/debug

Create a .vscode/launch.json file with this content. Change the port to match your debug port.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Attach to Minecraft Server",
      "request": "attach",
      "hostName": "localhost",
      "port": 55213
    }
  ]
}
```

--------------------------------

### ItemsAdder furniture place clue example

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/cluescrolls

Example of a ClueScrolls clue using the 'itemsadder_furnitureplace' clue type. The 'namespacedid' must match the ItemsAdder furniture's namespaced ID.

```yaml
examplefurnitureplaceclue:
  lore: '&d★ &fPlace an oak wood park bench'
  clueType: itemsadder_furnitureplace
  amount: 1
  objective: Place an oak wood park bench
  clueName: Furniture Placer
  data:
    namespacedid: 'itemsadder:oak_wood_park_bench'
```

--------------------------------

### Getting item on command

Source: https://wiki.itemsadder.com/developers/skript-api/expert-users-1

Demonstrates how to retrieve a custom item from ItemsAdder and add it to a player's inventory via a command.

```text
import:
  dev.lone.itemsadder.api.ItemsAdder

command /iaskript:
  trigger:
    set {testItem} to ItemsAdder.getCustomItem("itemsadder:ruby")
    sender.getInventory().addItem({testItem})
```

--------------------------------

### ItemsAdder block break clue example

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/cluescrolls

Example of a ClueScrolls clue using the 'itemsadder_blockbreak' clue type. The 'namespacedid' must match the ItemsAdder custom item's namespaced ID.

```yaml
examplebreakclue:
  lore: '&d★ &fBreak %amount% modern stone: %completed%'
  clueType: itemsadder_blockbreak
  amount: 12-16
  objective: Break %amount% modern stone
  clueName: Modern Stone Breaker
  data:
    namespacedid: 'iasurvival:modern_stone'
```

--------------------------------

### Configure open_back and open_front properties

Source: https://wiki.itemsadder.com/adding-content/items/bundle

Required YAML configuration for the bundle's open textures. Both properties must be set to the correct item paths, then run /iazip and accept the updated resource pack.

```yaml
open_back: item/bundles/ruby_bundle_open_back
open_front: item/bundles/ruby_bundle_open_front
```

--------------------------------

### ItemsAdder entity configuration YAML

Source: https://wiki.itemsadder.com/adding-content/entities/advanced-method

Example configuration file automatically created by the ItemsAdder extension on first export. Customize properties like display name, base entity type, model folder, and attributes.

```yaml
info:
  namespace: custom
entities:
  barman_robot:
    display_name: "Barman Robot"
    type: ZOMBIE
    model_folder: entity/barman_robot
    silent: true
    can_sun_burn: false
    speed:
      movement: 1
      flying: 0
    max_health: 20
      
```

--------------------------------

### MiniMessage text examples with hex and gradient colors

Source: https://wiki.itemsadder.com/plugin-usage/beginners/text-formatting

Example text lines showing MiniMessage formatting: hex color <#FE5A00>, color tags <red> and <green>, and a gradient tag <gradient:#ff00ee:#f79459>.

```text
<#FE5A00>Magic Fuel
<red>Magic <green>Fuel
<gradient:#ff00ee:#f79459>Here is a gradient example text!
```

--------------------------------

### Step 1: Create 2D icon item (2d_furniture)

Source: https://wiki.itemsadder.com/adding-content/furnitures/furniture-2d-icon

Defines the 2D icon item that places the furniture on right-click or shift-right-click. Uses a generated PAPER texture from 'item/2d_furniture' and references the 'furniture' item to place.

```yaml
info:
  namespace: myitems
items:
  2d_furniture:
    display_name: 2d_furniture
    permission: 2d_furniture
    resource:
      material: PAPER
      generate: true
      textures:
      - item/2d_furniture
    events:
      interact:
        right:
          place_furniture:
            furniture: furniture
            decrement_amount: true
        right_shift:
          place_furniture:
            furniture: furniture
            decrement_amount: true
```

--------------------------------

### config.yml hosting for secondary servers (external-host)

Source: https://wiki.itemsadder.com/faq/bungeecord-velocity/single-resourcepack-bungeecord

Use this hosting configuration on the other servers (survival, creative) to point to the pack URL obtained from /iainfo on the source server. Replace YOUR_PACK_COMPLETE_URL with the full URL, omitting any fragment after #. Reload ItemsAdder after changing the URL.

```yaml
resource-pack:
  hosting:
    no-host:
      enabled: false
    simple_self_host:
      enabled: false
      server_address: auto
    lobfile:
      enabled: false
    self-host:
      enabled: false
      server-ip: 127.0.0.1
      pack-port: 8163
    external-host:
      enabled: true
      url: 'YOUR_PACK_COMPLETE_URL'
```

--------------------------------

### Example Java script class

Source: https://wiki.itemsadder.com/adding-content/scripting/java/debug

A complete example of a Java script class extending ItemScript. It logs the player name and item ID, sends a message, and gives a diamond. The package must match the folder structure.

```java
package iascript;

import org.bukkit.Material;
import org.bukkit.event.Event;
import org.bukkit.plugin.Plugin;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import dev.lone.itemsadder.api.*;
import dev.lone.itemsadder.api.scriptinginternal.*;
import static dev.lone.itemsadder.api.scriptinginternal.ScriptingUtils.*;

public class example extends ItemScript {
    public void handleEvent(Plugin plugin, Event event, Player player, CustomStack $customStack, ItemStack $itemStack) {
        log("Player " + player.getName() + " interacted with item: " + $customStack.getNamespacedID());

        player.sendMessage("Hello from example script!");
        player.getInventory().addItem(new ItemStack(Material.DIAMOND, 1));
    }
}
```

--------------------------------

### getCustomItemDurability

Source: https://wiki.itemsadder.com/developers/java-api/old-api

Gets the custom durability of an item.

```APIDOC
## getCustomItemDurability

### Description
Gets the custom durability of an item.

### Method
getCustomItemDurability(ItemStack itemStack)

### Parameters
- **itemStack** (ItemStack) - Required - The item stack.

### Returns
- **int** - The custom durability value.

```

--------------------------------

### Step 2: Create the placed block item configuration (YAML)

Source: https://wiki.itemsadder.com/adding-content/blocks/block-2d-icon

Defines the 'rocks_placed' item that shows the placed rock model, and also includes the 'rocks' item from step 1. Requires a 'placed_rocks.json' model file in the specified folder.

```yaml
info:
  namespace: myitems
items:
  rocks_placed:
    display_name: ""
    permission: admin.blocks.rocks_placed
    resource:
      material: PAPER
      generate: false
      model_path: block/rocks_placed
    behaviours:
      block:
        placed_model:
          type: REAL_WIRE
        cancel_drop: true
        sound:
          place:
            name: block.stone.place
    events:
      placed_block:
        break:
          drop_item:
            item: rocks
  rocks:
    display_name: Rocks
    permission: blocks.rocks
    lore:
     - 'lore-decorative-item'
    resource:
      material: PAPER
      generate: true
      textures:
      - item/rocks
    events:
      interact:
        right:
          set_block:
            block: rocks_placed
            target: RELATIVE
            decrement_amount: true
        right_shift:
          set_block:
            block: rocks_placed
            target: RELATIVE
            decrement_amount: true
```

--------------------------------

### getCustomBlockLoot

Source: https://wiki.itemsadder.com/developers/java-api/old-api

Gets custom block loots.

```APIDOC
## getCustomBlockLoot

### Description
Gets custom block loots.

### Method
getCustomBlockLoot(Block block, ItemStack tool, boolean includeSelfBlock)

### Parameters
- **block** (Block) - Required - The block to get loot from.
- **tool** (ItemStack) - Required - The tool used to break the block.
- **includeSelfBlock** (boolean) - Required - Whether to include the block itself in the loot.

### Returns
- **List<ItemStack>** - A list of item stacks representing the loot.

```

--------------------------------

### Configure MythicMobs Drops with ItemsAdder items

Source: https://wiki.itemsadder.com/compatibility-with-other-plugins/compatible/mythicmobs

Example showing how to configure a mob to drop a custom item with a 30% chance and a quantity range of 1 to 5.

```yaml
ninja_skeleton:
  Type: ZOMBIE
  Display: '&aNinja Skeleton'
  Health: 10
  Damage: 2
  Drops:
    - myitems:special_sword 1-5 30%
  Options:
    MovementSpeed: 0
    Silent: true
  Skills:
  - customentity{model=custom:ninja_skeleton} @self ~onSpawn
  - customentity{play=attack} @self ~onAttack
  - customentity{walk=b_walk} @self ~onAttack
```

--------------------------------

### getCustomItemMaxDurability

Source: https://wiki.itemsadder.com/developers/java-api/old-api

Gets the maximum custom durability of an item.

```APIDOC
## getCustomItemMaxDurability

### Description
Gets the maximum custom durability of an item.

### Method
getCustomItemMaxDurability(ItemStack itemStack)

### Parameters
- **itemStack** (ItemStack) - Required - The item stack.

### Returns
- **int** - The maximum custom durability value.

```

--------------------------------

### Configure complete crop growth settings

Source: https://wiki.itemsadder.com/adding-content/crops

Define growth timing, light requirements, sounds, and environmental multipliers.

```yaml
crops:
  red_crop:
    models_by_textures:
      parent: minecraft:block/crop
      textures_prefix: block/red_crop_stage_
      model_texture_key: crop
    max_age: 7
    hitbox_auto_height_step: 0.1
    avg_seconds_per_stage: 240
    min_light: 9
    place_sound: minecraft:item.crop.plant
    break_sound: minecraft:block.crop.break
    multipliers:
      bonemeal: 0.2
      max_moisture: 0.5
      rain: 0.7
      thunderstorm: -0.5
      snow: -0.7
```

--------------------------------

### getCustomItemName

Source: https://wiki.itemsadder.com/developers/java-api/old-api

Gets the name of the item in config (e.g., 'ruby_pickaxe').

```APIDOC
## getCustomItemName

### Description
Gets the name of the item in config.

### Method
getCustomItemName(ItemStack itemStack)

### Parameters
- **itemStack** (ItemStack) - Required - The item stack.

### Returns
- **String** - The name of the item in config.

```

--------------------------------

### getCustomSeedNameFromCrop

Source: https://wiki.itemsadder.com/developers/java-api/old-api

Gets the custom seed name of a custom crop.

```APIDOC
## getCustomSeedNameFromCrop

### Description
Gets the custom seed name of a custom crop.

### Method
getCustomSeedNameFromCrop(Block block)

### Parameters
- **block** (Block) - Required - The crop block.

### Returns
- **String** - The name of the custom seed.

```

--------------------------------

### Dismounting entities

Source: https://wiki.itemsadder.com/adding-content/entities/mythicmobs

Syntax and examples for removing passengers from mount bones.

```text
- dismountentity{bones=BONE1,BONE2,BONE3} TARGETER ~EVENT
```

```text
- dismountentity{bones=BONE1} TARGETER ~EVENT
```

```text
- dismountentity{all=true} TARGETER ~EVENT
```

```text
- dismountentity{bones=mount1,mount2} @self ~onDamaged
- dismountentity{all=true} @self ~onDamaged
```

--------------------------------

### Bundle item YAML configuration

Source: https://wiki.itemsadder.com/adding-content/items/other-items-examples/bundle

Defines a bundle item named 'example_bundle' with a display name, permission, and a generated resource using the BUNDLE material and a custom texture. Requires a separate texture file with `_filled` suffix, e.g., `bundle_test_filled.png`.

```yaml
items:
  example_bundle:
    display_name: "&6&lExample Bundle"
    permission: example_bundle
    resource:
      material: BUNDLE
      generate: true
      textures:
      - item/bundle_test.png

```