CustomJoinItems

✨ CustomJoinItems v1.3 – Full Update for 1.21.8+
CustomJoinItems is a lightweight and powerful plugin built for Paper/Spigot 1.21.8+. It gives players custom items when they join or respawn, with full PlaceholderAPI support and several utility features designed for lobbies and hubs.

✅ What's New in This Version
New Elytra & Firework Support
Players can now receive an Elytra and rocket on join or respawn — fully configurable.

World-Based Item Control
Enable or disable join items depending on the world. Perfect for servers with multiple worlds and unique hub setups.

Permission-Based Elytra Toggle
Grant or deny Elytra usage via permissions, giving you per-player/group control.

Inventory Cleanup & Item Dropping
Automatically remove or drop unwanted items from player inventories.

Changelog Notes System
Track updates more clearly with built-in changelog support.

Improved NoteBlockAPI Support
Smoother .nbs music playback with fewer timing issues.

Performance Optimizations
Faster startup and reduced memory usage across all features.

Bug Fixes
Fixed rare cases where items were not properly delivered on respawn or death.

⚙️ General Features

• Give players custom items on join and respawn.
  
  
• Full PlaceholderAPI integration for dynamic content.
  
  
• Execute commands or teleport to BungeeCord/Velocity servers.
  
  
• Full control over item slots, including off-hotbar support (e.g., slot 35).
  
  
• Player visibility toggle with dynamic ON/OFF item.
  
  
• Teleport Bow with optional arrow delivery.
  
  
• Debugging tools for developers and admins.
  
  
• Automatically assign PLAYER_HEAD items with player skins.
  
  
• Music playback using NoteBlockAPI and .nbs files.
  
  
• Double Jump & Jump Pads enabled via permissions and fully configurable.
  
  
• Optional MySQL integration to store player data.
  

Installation
Drop CustomJoinItems-1.3.jar into your /plugins folder.
Install PlaceholderAPI (required for placeholder support).
Restart your server or run /customjoinitems reload.
Configure config.yml to suit your needs.
You're all set! Enjoy the most complete join item system for your hub.

Commands

• /customjoinitems reload – Reload the plugin configuration.
  

Permissions

• customjoinitems.menu – Grants the menu item.
  
  
• customjoinitems.perfil – Grants the profile item.
  
  
• customjoinitems.doublejump – Enables double jump.
  
  
• customjoinitems.jumppad – Enables use of jump pads.
  
  
• customjoinitems.teleportbow – Grants access to teleport bow.
  
  
• customjoinitems.elytra – Grants Elytra usage.
  

Requirements & Dependencies

• Paper or Spigot server version 1.21.8+
  
  
• PlaceholderAPI (recommended)
  
  
• NoteBlockAPI (optional – for music playback via .nbs files)
  
  
• BungeeCord & Velocity compatible (via configurable commands)
  

️ Technical Notes

• If an item has both command and server defined, the command has priority.
  
  
• When using PLAYER_HEAD, the item automatically shows the player’s skin.
  
  
• Items can be assigned to any inventory slot, including slot 35 (outside the hotbar).
  
  
• Double jump, Elytras, and jump pads are fully permission-based and customizable.
  

• 
  
  
  

  # ✅ Enable or disable debug mode. If true, useful messages will be shown in console.
  debug: false
  
  # Custom music settings
  music:
    # Link to a video or song that will be shown in chat when the player joins (e.g., a YouTube video)
    link: "https://youtu.be/TuLinkDeEjemplo"
  
    # If enabled, the song will play automatically when the server starts
    autoPlayOnStart: true
  
    # List of sound notes to be played at the start. Each entry has:
    # - delay: time in ticks (20 ticks = 1 second)
    # - sound: a valid sound like BLOCK_NOTE_BLOCK_*
    # - pitch: pitch of the note
    notes:
      - { delay: 0,  sound: BLOCK_NOTE_BLOCK_BASS,   pitch: 0.5 }
      - { delay: 4,  sound: BLOCK_NOTE_BLOCK_BELL,   pitch: 1.0 }
      - { delay: 8,  sound: BLOCK_NOTE_BLOCK_HAT,    pitch: 1.2 }
      - { delay: 12, sound: BLOCK_NOTE_BLOCK_GUITAR, pitch: 0.8 }
      - { delay: 16, sound: BLOCK_NOTE_BLOCK_PLING,  pitch: 1.5 }
  
  # Sound when changing slots in the hotbar
  hotbar-switch:
    enabled: true            # true to enable the effect
    sound: BLOCK_NOTE_BLOCK_BIT
    volume: 1.0
    pitch: 1.0
  
  # Worlds where items will be automatically given to players
  allowed-worlds:
    - Lobby
  
  # List of item identifiers that will be given to the player. Referenced below in item-settings.
  items:
    - menu
    - perfil
    - Coleccionables
    - visibility_toggle
  
  # Individual item configuration
  item-settings:
    menu:
      enabled: true
      material: COMPASS
      name: "<dark_aqua><bold>Game Menu</bold> <white>(Right Click)"
      lore:
        - "<gold>▸ <white>Explore all our game modes and events"
        - "<aqua><italic>Right click to open the menu!</italic>"
      slot: 0
      permission: "customjoinitems.menu"
      command: "menu_bb"
      worlds:
        - Lobby
  
    Coleccionables:
      enabled: true
      material: CLOCK
      name: "<green><bold>Collectibles</bold> <gray>(Right Click)"
      lore:
        - "<gold>Mystery Dust: <white>{mystery_dust}"
        - "<white><italic>Discover unique cosmetics!</italic>"
      slot: 8
      permission: "customjoinitems.perfil"
      command: "gm 3"
      worlds:
        - Lobby
  
    perfil:
      enabled: false
      material: PLAYER_HEAD    # Automatically gives the player's head
      name: "<green><bold>My Profile</bold> <white>(Right Click)"
      lore:
        - "<gold>▸ <white>Check your stats and achievements"
      slot: 1
      permission: "customjoinitems.perfil"
      command: "gm 3"
      worlds:
        - Lobby
  
    visibility_toggle:
      enabled: false
      slot: 7
      permission: "customjoinitems.visibility"
      visible:        # Item shown when players are visible
        material: LIME_DYE
        name: "<red>Hide Players"
        lore:
          - "<gray>Click to hide other players."
      hidden:         # Item shown when players are hidden
        material: RED_DYE
        name: "<green>Show Players"
        lore:
          - "<gray>Click to show players again."
      worlds:
        - Lobby
  
    Lobby:
      enabled: true
      material: RED_BED
      name: "<red>Return to Lobby <gray>(Right Click)"
      lore:
        - "<gray>Right click to return to the lobby"
      slot: 8
      permission: "customjoinitems.perfil"
      server: "lobby"    # If no "command" is set, this item will send the player to a server
      worlds:
        - Lobby
  
  # Teleport Bow – teleports the player where the arrow lands
  teleport-bow:
    enabled: true
    slot: 4
    material: BOW
    name: "<light_purple><bold>Teleport Bow</bold> <white>(Right Click)"
    lore:
      - "<gray>Shoot to teleport."
    give-arrow: true            # If true, gives an arrow automatically
    arrow-slot: 35              # Inventory slot for the arrow (outside hotbar)
    cooldown: 2                 # Cooldown in seconds
    cooldown-message: "<gray>[<gold>Code</gold>] Wait <white>%seconds%</white>s to use the bow again."
    cooldown-sound: BLOCK_NOTE_BLOCK_BASS
    cooldown-particle: SMOKE
    shoot-sound: ENTITY_ARROW_SHOOT
    shoot-particle: CRIT
    hit-sound: ENTITY_ENDERMAN_TELEPORT
    hit-particle: PORTAL
    worlds:
      - Lobby
  
  # Jump Pad – launches player when stepping on a block
  jump-pad:
    enabled: true
    permission: "customjoinitems.jumppad"
    cooldown: 5
    sound: BLOCK_AMETHYST_BLOCK_CHIME
    particle: SPELL_INSTANT
    vertical_multiplier: 1.0
    forward_multiplier: 4.1
  
  # Double Jump – allows a second jump mid-air
  double-jump:
    enabled: true
    permission: "customjoinitems.doublejump"
    cooldown: 10
    sound: BLOCK_AMETHYST_BLOCK_CHIME
    particle: CLOUD
    vertical_multiplier: 1.2
    forward_multiplier: 2.1
  
  # Database configuration (MySQL)
  database:
    enabled: false
    host: "localhost"
    port: "3306"
    name: "minecraft"
    user: "root"
    password: "password"
  
  # Whether to give items on death (true = yes, false = only on join)
  give-items-on-death: true
  
  # Customizable messages sent to players
  messages:
    visibility-on: "<green>You can now see all players."
    visibility-off: "<red>You have hidden all players."
    protection-enabled: "<green>Item protection enabled."
    protection-disabled: "<red>Item protection disabled."
    protection-no-permission: "<red>You don't have permission to use this command."
    protection-usage: "<yellow>Usage: /cji toggle"
  
  # Item protection toggle – /cji toggle command config
  cji:
    protection:
      permission: "customjoinitems.admin"
      cooldown: 5
      sound: ENTITY_EXPERIENCE_ORB_PICKUP
      particle: CLOUD
  
  # Custom command aliases
  commands:
    visibility: "visibility"
    aliases:
      leave: "bb leave"
  
  # ⚠️ Do not modify this structure unless you know what you're doing!