### Shopkeepers Configuration Item Example

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Data-Config-Format-Before-v2.24.0

A comprehensive example of an item configuration in Shopkeepers' YAML format, showcasing currency item settings including type, display name, lore, enchantments, and item flags.

```YAML
currency-item:
  type: EMERALD
  display-name: '{"text":"A fancy looking crystal","italic":false,"color":"green"}'
  lore:
  - '{"text":"It looks precious."}'
  - '{"text":"I might be able to sell it."}'
  enchants:
    DURABILITY: 1
  ItemFlags:
  - HIDE_ENCHANTS
```

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

### Example of Text Styling with '&'-based Codes

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Language-Files

Demonstrates how to apply text styling in language files using '&'-based color and formatting codes. For example, '&c' colors subsequent text red.

```yaml
&cThis text will be red.
```

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

### Example of Text Styling with Compact Hex Format

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Language-Files

Illustrates the use of a more compact format for applying hex colors to text, specified by '&#aabbcc'.

```yaml
&#aabbccThis text will be in a compact hex color.
```

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

### Example of Text Styling with Bukkit Hex Format

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Language-Files

Shows how to apply hex colors to text using Bukkit's hex format, which involves a sequence of '&x' followed by pairs of hex characters.

```yaml
&x&a&a&b&b&c&cThis text will be in a specific hex color.
```

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

### Example: Currency Item Configuration in Shopkeepers

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

An example YAML snippet showing how to define a currency item within the Shopkeepers plugin configuration. It includes specifying the item ID and custom components like name, lore, and enchantments.

```YAML
currency-item:
  id: 'minecraft:emerald'
  components:
    minecraft:custom_name: '{color:"green",italic:0b,text:"A fancy looking crystal"}'
    minecraft:lore: '[{text:"It looks precious."}, {text:"I might be able to sell it."}]'
    minecraft:enchantments: '{unbreaking:1}'
```

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

### Item Matching Example Configuration

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

This YAML snippet demonstrates how to define an item for shop creation, specifying its ID and custom name component. It illustrates the partial matching behavior where additional item data like lore or enchantments are permitted.

```yaml
shop-creation-item:
  id: 'minecraft:villager_spawn_egg'
  components:
    minecraft:custom_name: '{color:"green",italic:0b,text:"Shopkeeper"}'
```

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

### Give Player Head Command Example

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

Example of a Minecraft command to give a player a head item. This command specifies the SkullOwner, which Minecraft may later replace with a full profile including texture and timestamp. This can lead to issues with item stacking and trading if not handled properly.

```minecraft-command
/give @p player_head{SkullOwner:"MHF_Chest"} 1
```

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

### Getting Block Data with /data get

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

The Minecraft `/data get block` command can be used to inspect the internal data of items within a chest or other block entities. This is useful for comparing item NBT data.

```minecraft
/data get block <coords>
```

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

### Spigot Workaround for Turkish Locale Issue

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

For Spigot versions prior to 1.20.6 (specifically noted in 1.20.4), users with a Turkish locale encountered startup failures due to issues with 'i' character casing in text conversions. This workaround involves starting the server with English language and region parameters.

```bash
java -Duser.language=en -Duser.region=EN -jar spigot.jar
```

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

### CustomItems Plugin - Item NBT Data Example

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

This snippet shows the NBT data structure for an item created by the CustomItems plugin. This data can be used to investigate trading issues related to item configuration.

```json
{
  "id": "minecraft:bread",
  "tag": {
    "display": {
      "Name": '{"extra":[{"bold":false,"italic":false,"underlined":false,"strikethrough":false,"obfuscated":false,"color":"#EAAE69","text":"Cuernito"}],"text":""}',
      "Lore": [
        '{"extra":[{"bold":false,"italic":true,"underlined":false,"strikethrough":false,"obfuscated":false,"color":"#714AB2","text":"\\"Ulala, un Croissant!\\""}],"text":""}'
      ]
    },
    "CustomModelData": 3,
    "com.jojodmo.customitems.itemID": "cuernito",
    "com.jojodmo.customitems.itemVersion": 1,
    "com.jojodmo.customitems.internalVersion": "1"
  },
  "Count": 64
}
```

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

### Identify Shopkeepers Plugin Inventory (Java)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

This example illustrates how to check if a specific inventory belongs to the Shopkeepers plugin by utilizing the UIRegistry and UISession. This method requires a dependency on the Shopkeepers API.

```Java
ShopkeepersAPI.getUIRegistry().getUISession(player)
```

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

### Custom Language File Naming Convention

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Language-Files

Illustrates the required naming pattern for custom language files, which must start with 'language-' followed by the language code and end with '.yml'.

```yaml
language-en-custom.yml
```

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

### MythicMobs Plugin - Legacy Color Code Issue

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

This example demonstrates how MythicMobs items may contain legacy color codes within modern text components, causing compatibility issues with plugins like Shopkeepers, especially on Paper servers. Items saved before the fix might not stack with newly created ones.

```plaintext
Items created by MythicMobs use legacy color codes within modern text components (eg. http://prntscr.com/we8kcs , serialized: http://prntscr.com/we8l0n).
```

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

### Configure OpenInv for Shopkeeper Chest Access (Commands)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

These commands are examples of how to disable 'invisible chest access' modes in the OpenInv plugin. These modes can conflict with the Shopkeepers plugin's ability to detect player chest access, preventing shop creation. Disabling these modes is necessary for admins to create player shops.

```command
/openinv silentcontainer off
```

```command
/openinv anycontainer off
```

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

### Example Configuration for German Language

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Language-Files

This snippet shows how to configure the Shopkeepers plugin to use the German language translation by setting the 'language' option in the configuration file.

```yaml
language: de
```

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

### Shopkeepers Plugin Commands Reference

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

This section lists and describes various commands used to manage shopkeepers and their associated shops within the Shopkeepers plugin. Commands are categorized by their function, such as general help, shop creation, removal, currency management, and permission settings. Each command entry includes its syntax, arguments (optional and required), and a brief explanation of its purpose and any prerequisites.

```bash
/shopkeeper help
/shopkeeper [shop-type] [object-type]
/shopkeeper reload
/shopkeeper notify <'trades'>
/shopkeeper list [player|'admin'|'all'] [page]
/shopkeeper remove [shop]
/shopkeeper removeAll [player|'player'|'admin']
/shopkeeper give [player] [amount]
/shopkeeper giveCurrency [player] ['base'|'high'] [amount]
/shopkeeper setCurrency ['base'|'high']
/shopkeeper remote [shop] [player]
/shopkeeper edit [shop]
/shopkeeper transfer <newOwner>
/shopkeeper setTradePerm [shop] <permission|'-'|'?'>
/shopkeeper setTradedCommand <command|'-'|'?'>
/shopkeeper setForHire [shop]
```

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

### Configure Knowledge Book Recipes (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the structure for a knowledge book, where you can list discovered recipes. Recipes are specified using a namespaced key format.

```YAML
Recipes:
- <namespace>:<key>
- <namespace>:<key>
```

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

### Display Server Statistics

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Prints statistics related to the server, including loaded chunks, entities, loaded shopkeepers, and processing times for AI and gravity. This command is useful for performance monitoring.

```command
/shopkeeper check
```

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

### Debug Mode for Trade Failures

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

Enabling debug mode can provide detailed console logs when a trade fails, aiding in the diagnosis of item matching issues. This is a server-side configuration.

```yaml
debug-mode: true
```

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

### Shopkeepers Plugin Directory Structure

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Installation-and-Updating

Illustrates the file and folder organization created by the Shopkeepers plugin within a Bukkit/Spigot server's plugins directory. This includes configuration files, data storage, language files, and trade logs.

```ruby
../plugins/ # The server's plugins folder
    +--Shopkeepers/ # Base directory for the plugin
        |-- config.yml # Configuration
        +-- data/
            |-- save.yml # Saved shopkeeper data (shops, trade offers, ..)
            |-- save.yml.tmp # Temporary file, only exists briefly while saving the shopkeeper data
        +-- lang/
            |-- language-en-default.yml # Default language file, cannot be modified, acts as template for custom language files
            |-- # Additional language files (optional)
        +-- trade-logs/
            |-- # CSV trade log files (if trade logging is enabled in the config)

```

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

### Create Admin Shop Command

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Creating-Shops

This command is used to create an admin shop. The shopkeeper entity will spawn at the block the player is looking at. Ensure you are looking at a non-chest block. Further configuration for trades is done separately.

```text
/shopkeeper [object type]
```

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

### Create Player Shop Command

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Creating-Shops

Command to create player shops, with optional shop and object types. This command requires the 'create-player-shop-with-command' setting to be enabled in the configuration. The target block must be a chest or supported container.

```command
/shopkeeper [shop type] [object type]
```

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

### Create Test Shopkeepers

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Generates shopkeepers for testing purposes. If 'testEquipment' is specified, it creates shopkeepers with default equipment for each mob type to test slot support. Otherwise, it creates a specified number of admin shopkeepers for performance testing. Shopkeepers are spawned in a line relative to the player's position and facing direction.

```command
/shopkeeper debugCreateShops [shopCount|'testEquipment']
```

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

### Skipping Custom Head Saving

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

A configuration option to test support for head items with custom textures. Enabling this setting on older server versions might prevent data corruption when saving such items. Use with caution.

```yaml
skip-custom-head-saving: true
```

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

### Configure Bundle with ItemStacks (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the content of a bundle by listing the ItemStacks it contains. Each item within the bundle follows the standard ItemStack format.

```YAML
items:
- <ItemStack>
- < ... more ItemStacks >
```

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

### Delay Command Execution by 1 Tick (Denizen)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

This Denizen script demonstrates how to delay the execution of a command, specifically 'shopkeeper open <id>', by 1 tick. This is a workaround for potential conflicts with plugins that handle inventory events immediately, ensuring the command is processed after other event handlers.

```yaml
openShopkeeper:
  type: task
  debug: false
  script:
  - wait 1t
  - execute as_player "shopkeeper open <id>"
```

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

### Define Command Aliases (Bukkit commands.yml)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Selling-Commands

Defines custom command aliases in Bukkit's 'commands.yml' file to chain multiple commands or create simplified command structures. This is a workaround for the limitation of assigning only a single command directly to an item.

```yaml
aliases:
  mytradecommand:
    - "tellraw {player_name} \"Thanks for the trade!\""
    - "eco give {player_name} 50"

```

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

### Manage Shopkeeper Snapshots

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Commands to manage shopkeeper snapshots, including listing, creating, removing, and restoring them. Creating and removing snapshots requires editing rights for the target shopkeeper. Snapshot names cannot contain color codes or spaces.

```command
/shopkeeper snapshot list [shop] [page]
```

```command
/shopkeeper snapshot create [shop] <name>
```

```command
/shopkeeper snapshot remove [shop] <name|id>
```

```command
/shopkeeper snapshot restore [shop] <name|id>
```

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

### Give Shop Creation Item Command

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Creating-Shops

Admin command to give the shop creation item to yourself. This item is essential for creating player shops. Usage requires appropriate administrative privileges.

```command
/shopkeeper give
```

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

### Writable Book Pages Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the structure for writable book pages, storing them as plain text. Each element in the 'pages' list represents a page of text.

```yaml
pages:
- <page text>
- < ... more pages >
```

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

### Shopkeepers Plugin Permissions Configuration (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Permissions

This YAML snippet defines the permission nodes for the Shopkeepers plugin. It includes command-specific permissions for actions like reloading, debugging, listing shops, removing shops, and managing currency, as well as general permissions for trading and hiring. The 'default' key indicates if the permission is true for everyone, op, or needs to be explicitly granted.

```YAML
permissions:
    # Command permissions:
    shopkeeper.help:
        description: Display the command help
        default: true
    shopkeeper.reload:
        description: Reload the plugin
        default: op
    shopkeeper.debug:
        description: Toggle debug mode and access debugging commands
        default: op
    shopkeeper.cleanup-citizen-shopkeepers:
        description: Delete invalid Citizen shopkeepers via command
        default: op

    shopkeeper.list.own:
        description: List your own player shops
        default: true
    shopkeeper.list.others:
        description: List the player shops of other players
        default: op
    shopkeeper.list.admin:
        description: List the admin shops
        default: op

    shopkeeper.remove.own:
        description: Remove your own shops via command
        default: op
    shopkeeper.remove.others:
        description: Remove the shops of other players via command
        default: op
    shopkeeper.remove.admin:
        description: Remove admin shops via command
        default: op

    shopkeeper.remove-all.own:
        description: Remove all of your own shops via command
        default: op
    shopkeeper.remove-all.others:
        description: Remove all the shops of another player via command
        default: op
    shopkeeper.remove-all.player:
        description: Remove the player shops of all players via command
        default: op
    shopkeeper.remove-all.admin:
        description: Remove all admin shops via command
        default: op

    shopkeeper.notify.trades:
        description: Allows turning trade notifications for you on or off by command
        default: true
    shopkeeper.give:
        description: Give shop creation items via command
        default: op
    shopkeeper.givecurrency:
        description: Give currency items via command
        default: op
    shopkeeper.setcurrency:
        description: Set the currency items via command
        default: op
    shopkeeper.convertitems.own:
        description: Convert your own items via command
        default: op
    shopkeeper.convertitems.others:
        description: Convert items of other players via command
        default: op
    shopkeeper.updateitems:
        description: Update third-party items
        default: op
    shopkeeper.remote:
        description: Remotely open shops via command
        default: op
    shopkeeper.remote.otherplayers:
        description: Remotely open shops for other players
        default: op
    shopkeeper.remoteedit:
        description: Remotely edit shops via command
        default: op
    shopkeeper.transfer:
        description: Transfer ownership of player shops
        default: op
    shopkeeper.teleport:
        description: Teleport to shopkeepers via command
        default: op
    shopkeeper.teleport.others:
        description: Teleport other players to shopkeepers
        default: op
    shopkeeper.settradeperm:
        description: Set the trade permissions for admin shops
        default: op
    shopkeeper.settradedcommand:
        description: Set the traded command for the held item
        default: op
    shopkeeper.setforhire:
        description: Set a shopkeeper to be for hire
        default: op
    shopkeeper.snapshot:
        description: Access shopkeeper snapshot commands
        default: op
    shopkeeper.edit-villagers:
        description: Edit regular villagers
        default: op
    shopkeeper.edit-wandering-traders:
        description: Edit regular wandering traders
        default: op

    # General permissions
    shopkeeper.trade:
        description: Allows trading with shopkeepers
        default: true
    shopkeeper.hire:
        description: Allows hiring of shopkeepers
        default: true
    shopkeeper.bypass:

```

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

### Compact Item Representation in Shopkeepers Config

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

Demonstrates a simplified format for specifying items without special data in the Shopkeepers plugin configuration. This is an alternative to the more verbose id-based format, making manual configuration easier.

```YAML
shop-creation-item: 'minecraft:villager_spawn_egg'
```

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

### JSON Text Format for Display Name in Shopkeepers Config

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Data-Config-Format-Before-v2.24.0

Illustrates the recommended JSON text format for specifying item display names in the Shopkeepers configuration. This replaces legacy color codes for better compatibility.

```YAML
display-name: '{"text":"Shopkeeper","italic":false,"color":"green"}'
```

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

### Colorable Armor Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Combines armor trim and color components for colorable armor types. Includes trim materials/patterns and RGBA color values.

```yaml
trim:
  material: <trim material namespaced key>
  pattern: <trim pattern namespaced key>
color:
  ==: Color
  ALPHA: <alpha value>
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>
```

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

### Compact Item Specification in Shopkeepers Config

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Data-Config-Format-Before-v2.24.0

Demonstrates a simplified YAML format for specifying items without special data in the Shopkeepers configuration. This is an alternative to the more verbose 'type' field format.

```YAML
shop-creation-item: VILLAGER_SPAWN_EGG
```

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

### Enable Shopkeepers Debug Mode via Configuration

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Troubleshooting

Enables the debug mode for the Shopkeepers plugin by setting the 'debug' option to true in the configuration file. This will cause the plugin to log additional information to the console or in-game. Ensure the configuration file is correctly formatted.

```yaml
debug: true
```

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

### Configure Goat Horn Instrument (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Specifies the instrument played by a goat horn using a namespaced key. Links to the Minecraft wiki for a list of available goat horn instruments are provided.

```YAML
instrument: <instrument namespaced key>
```

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

### Fabric/Lithium/Cardboard - Class Not Found Exception

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

This describes a 'class not found' exception for 'net/minecraft/class_1352' occurring when Shopkeepers initializes. This issue is suspected to be caused by modifications to the Shopkeepers plugin JAR, remapping NMS classes due to the use of Fabric/Cardboard, even after reverting to a Paper server.

```java
class net.minecraft.class_1352
```

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

### Strict Item Comparison Setting

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

This setting enforces a stricter comparison between required and offered items in trades. If enabled, trades will be prevented if the offered item has additional data not present in the required item, unlike Minecraft's more lenient approach.

```yaml
use-strict-item-comparison: true
```

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

### Written Book Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the structure for a signed written book, including title, author, pages (as JSON text), generation code, and resolved status.

```yaml
title: <book title>
author: <author name>
pages:
- <page text Json>
- < ... more pages >
generation: <generation code>
resolved: <true/false>
```

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

### Replace Shopkeepers with Vanilla Villagers

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Deletes all shopkeepers and replaces them with vanilla villagers. These vanilla villagers lack AI and are configured to be similar to shopkeeper villagers, useful for world migration. Mob equipment is not preserved. Requires specific debug, remove-all player, and remove-all admin permissions.

```command
/shopkeeper replaceAllWithVanillaVillagers
```

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

### Shopkeepers YAML Command Usage

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

Illustrates the usage of the `/shopkeepers yaml` command in the Shopkeepers plugin. This command is used to output the Bukkit YAML serialization of the item held in hand and its formatted item data for the config file. The output is also logged to the console.

```Text
/shopkeepers yaml
```

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

### Configure Enchanted Books with Stored Enchantments (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines how to specify enchantments and their levels for an enchanted book. It provides a mapping of enchantment IDs to their corresponding levels and links to Spigot Javadocs for available enchantments.

```YAML
stored-enchants:
  <enchantment id>: <enchantment level>
  < ... more enchantments >
```

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

### Trigger Third-Party Item Updates

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Initiates updates for items managed by third-party integrations. This command ensures that item data is synchronized across different systems.

```command
/shopkeeper updateItems
```

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

### Execute Command as Trading Player (Minecraft)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Selling-Commands

Uses the Minecraft '/execute' command to run a subsequent command as the trading player, rather than the server console. This allows for player-specific command execution within the traded item system.

```minecraft-commands
/execute as {player_name} run <command>

```

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

### Enable Color Codes in Shopkeeper Names (Configuration)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

This snippet shows how to modify the regular expression in the Shopkeepers plugin's configuration file to allow color codes in shopkeeper names. By default, certain characters like '&' and '§' might be excluded, preventing colored names. Ensure your config file is UTF-8 encoded for proper display.

```yaml
name-regex: [A-Za-z0-9&§ ]{3,25}
```

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

### Armor Trim Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Specifies the structure for armor trims, including the material and pattern as namespaced keys. This applies to various types of armor.

```yaml
trim:
  material: <trim material namespaced key>
  pattern: <trim pattern namespaced key>
```

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

### Invoke DenizenScript Script (DenizenScript)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Selling-Commands

Invokes a custom script written in DenizenScript using the '/ex' command. This is useful for implementing more complex trading behaviors, conditional commands, or random selections that are beyond the scope of the default traded command feature.

```denizenscript
/ex <script_name>

```

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

### Enable Villager Editor Configuration

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Editor-for-regular-villagers

Enables the ability to open the villager editor by sneaking and right-clicking a villager or wandering trader. These settings are typically found in the plugin's configuration file.

```plaintext
edit-regular-villagers=true
edit-regular-wandering-traders=true
```

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

### Configure Compass with Lodestone Information (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Details the configuration for a compass, allowing it to track a specific lodestone. This includes the lodestone's world name and coordinates, as well as a flag to indicate if it's being tracked.

```YAML
LodestonePosWorld: <lodestone world name>
LodestonePosX: <lodestone x coordinate>
LodestonePosY: <lodestone y coordinate>
LodestonePosZ: <lodestone z coordinate>
LodestoneTracked: <true|false>
```

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

### Shopkeeper Configuration Settings

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Trade-Notifications

Configuration settings for enabling and customizing trade notifications. These control whether shop owners and other players receive trade alerts and associated sounds.

```properties
notify-shop-owners-about-trades=true
notify-players-about-trades=false
trade-notification-sound=""
shop-owner-trade-notification-sound=""
```

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

### Configure Trade Log Storage Format - Shopkeepers Plugin

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Trade-Logging

This configuration snippet shows how to enable trade logging by setting the 'trade-log-storage' option in the plugin's configuration file. It supports DISABLED, SQLITE, and CSV formats, with SQLITE being recommended. Only one format can be active at a time.

```yaml
trade-log-storage: SQLITE
```

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

### Convert Shopkeeper Items

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Converts held or all items to Spigot's internal item data format by running them through serialization and deserialization. This can fix items not conforming to the expected format, especially useful after plugin reloads or for manual item correction. Note: May have reduced effect on newer Spigot versions due to item data persistence.

```command
/shopkeeper convertItems [player] ['all']
```

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

### Configure Shopkeepers for Magma and Mohist

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

When using Shopkeepers with Magma or Mohist servers, specific configuration settings can help resolve trading UI issues. The `ignore-failed-server-assumption-tests` option can be enabled to risk running the plugin despite potential item comparison failures. For Magma, setting `disable-inventory-verification` to `true` in the Shopkeepers config can resolve issues with the trading UI closing unexpectedly.

```yaml
shopkeepers:
  ignore-failed-server-assumption-tests: true

magma:
  disable-inventory-verification: true
```

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

### Configure Ominous Bottle Amplifier (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the amplifier level for an ominous bottle. The amplifier must be an integer between 0 and 4, affecting the bottle's potency. A link to the Minecraft wiki for more details is included.

```YAML
ominous-bottle-amplifier: <ominous bottle amplifier level>
```

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

### Configure Crossbow with Charged Projectiles (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Specifies how to define a crossbow with charged projectiles. The projectiles themselves are defined using the same item stack format described on this page.

```YAML
charged-projectiles:
- <serialized arrow item (uses the same format as described on this page)>
- < ... more serialized arrow items >
```

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

### Enable Item Metadata Logging - Shopkeepers Plugin

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Trade-Logging

This configuration snippet demonstrates how to enable the logging of detailed item metadata, such as display names and lore, in addition to item types. Setting 'log-item-metadata' to true expands the log file content.

```yaml
log-item-metadata: true
```

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

### Shopkeepers Item Data Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the common data structure for all items in shopkeepers, including essential properties like type, amount, and metadata. It also details advanced configurations for enchantments, attributes, tools, food effects, and more.

```yaml
path-to-item:
  ==: org.bukkit.inventory.ItemStack
  v: <Minecraft data version>
  type: <item type name>
  amount: <stack size>
  meta:
    ==: ItemMeta
    meta-type: <meta type id>
    item-name: <item name Json, see https://minecraft.wiki/w/Data_component_format#item_name>
    display-name: <custom name Json, see https://minecraft.wiki/w/Data_component_format#custom_name>
    lore:
    - <lore line Json, see https://minecraft.wiki/w/Data_component_format#lore>
    - < ... more lore lines >
    custom-model-data: <custom model data integer value, see https://minecraft.wiki/w/Data_component_format#custom_model_data>
    max-stack-size: <max stack size, see https://minecraft.wiki/w/Data_component_format#max_stack_size>
    rarity: <rarity name, see https://minecraft.wiki/w/Data_component_format#rarity>
    BlockStateTag:
      <key>: <value>
      < ... more block states, see https://minecraft.wiki/w/Data_component_format#block_state>
    enchants:
      <enchantment namespaced key>: <enchantment level>
      < ... more enchantments >
    enchantment-glint-override: <true/false, see https://minecraft.wiki/w/Data_component_format#enchantment_glint_override>
    attribute-modifiers: # See https://minecraft.wiki/w/Data_component_format#attribute_modifiers
      <attribute namespaced key>:
      - ==: org.bukkit.attribute.AttributeModifier
        key: <arbitrary modifier namespaced key>
        operation: <operation id>
        amount: <amount>
        slot: <slot group name>
      - < ... more attribute modifiers >
      < ... more attributes >
    ItemFlags:
    - <item flag name>
    - < ... more item flag names >
    hide-tool-tip: <true/false, see https://minecraft.wiki/w/Data_component_format#hide_tooltip>
    Unbreakable: <true|false, see https://minecraft.wiki/w/Data_component_format#unbreakable>
    fire-resistant: <true/false, see https://minecraft.wiki/w/Data_component_format#fire_resistant>
    Damage: <damage, see https://minecraft.wiki/w/Data_component_format#damage>
    max-damage: <max damage, see https://minecraft.wiki/w/Data_component_format#max_damage>
    repair-cost: <repair cost, see https://minecraft.wiki/w/Data_component_format#repair_cost>
    tool:
      ==: Tool
      default-mining-speed: <float>
      damage-per-block: <integer>
      rules:
      - ==: ToolRule
        blocks: <Either a `#`-prefixed block tag namespaced key, or a list of block namespaced keys>
        speed: <float>
        correct-for-drops: <true/false>
      - < ... more tool rules >
    food:
      ==: Food
      nutrition: <integer>
      saturation: <float>
      can-always-eat: <true/false>
      eat-seconds: <float>
      using-converts-to: <serialized ItemStack>
      effects:
      - ==: FoodEffect
        effect:
          ==: PotionEffect
          effect: <effect type id>
          duration: <duration>
          amplifier: <amplifier>
          ambient: <true|false>
          has-particles: <true|false>
        probability: <float>
      - < ... more food effects >
    jukebox-playable:
      ==: JukeboxPlayable
      song: <song namespaced key, see https://minecraft.wiki/w/Data_component_format#jukebox_playable>
      show-in-tooltip: <true/false>
    PublicBukkitValues: <custom plugin data as SNBT string>
    custom: <custom data encoded as base64 text, see https://minecraft.wiki/w/Data_component_format#custom_data>
    internal: <other data encoded as base64 text>
    unhandled: <unhandled data encoded as base64 text>
```

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

### Configure Firework Rockets with Custom Effects (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Details the structure for creating custom firework rockets, including defining multiple firework effects. Each effect can have flicker, trail, custom colors, fade colors, and a specific type. Power determines flight duration. Color values range from 0 to 255, and power from 0 to 127.

```YAML
firework-effects:
- ==: Firework
  flicker: <true|false>
  trail: <true|false>
  colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  fade-colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  type: <firework effect type name>
- < ... more firework effects >
power: <power>
```

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

### Force Shopkeepers Fallback Mode via File

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Troubleshooting

Forcefully enables the fallback mode for the Shopkeepers plugin by creating a specific file in the plugin's data folder. This mode is used when the server version is not officially supported and is prone to breaking with server updates. It is recommended to keep backups.

```file-creation
.force-fallback
```

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

### Shield Patterns Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the structure for shield customization, including base color and a list of patterns. This allows for complex designs on shields.

```yaml
base-color: <color name>
patterns:
- ==: Pattern
  color: <color name>
  pattern: <pattern code>
- < ... more patterns >
```

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

### Open Villager Editor Command

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Editor-for-regular-villagers

Opens the villager editor for a targeted villager or wandering trader. Requires specific permissions or configuration.

```plaintext
/shopkeepers editVillager [villager]
```

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

### Enable Shopkeepers Debug Mode via Command

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Troubleshooting

Enables the debug mode for the Shopkeepers plugin using the in-game command. The option parameter can be used to specify specific debug logging behavior. This is an alternative to modifying the configuration file directly.

```minecraft-command
/shopkeeper debug [option]
```

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

### Configure Firework Stars with Custom Effects (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Describes the configuration for a firework star, allowing customization of its visual effects. This includes flicker, trail, primary colors, fade colors, and the effect type. Color values range from 0 to 255.

```YAML
firework-effect:
  ==: Firework
  flicker: <true|false>
  trail: <true|false>
  colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  fade-colors:
  - ==: Color
    ALPHA: <alpha value>
    RED: <red value>
    GREEN: <green value>
    BLUE: <blue value>
  - < ... more colors >
  type: <firework effect type name>
```

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

### Configure Suspicious Stew Effects (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Specifies the data format for suspicious stew, allowing for the definition of custom potion effects, including type, duration, and amplifier. It references the Minecraft wiki for available effect IDs.

```YAML
effects:
- ==: PotionEffect
  effect: <effect type id>
  duration: <duration>
  amplifier: <amplifier>
  ambient: <true|false>
  has-particles: <true|false>
- < ... more potion effects >
```

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

### Check Held Items Debug Info

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Prints debug information about the items the player is currently holding, including a comparison between main and off-hand items. This command is useful for diagnosing item-related issues.

```command
/shopkeeper checkitem
```

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

### Identify Custom Merchants (Java)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

This snippet shows how to determine if a Merchant is a custom plugin-created merchant, specifically checking if it's an instance of AbstractVillager. This method doesn't require a Shopkeepers plugin dependency.

```Java
merchant instanceof AbstractVillager
```

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

### Shop Creation Item Tag Configuration

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

These YAML settings control how the 'shop_creation_item' is identified. 'add-shop-creation-item-tag' enables the addition of a custom tag, while 'identify-shop-creation-item-by-tag' dictates whether this tag is used for identification, overriding the default item matching.

```yaml
add-shop-creation-item-tag: true
identify-shop-creation-item-by-tag: true
```

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

### Configure Potions with Custom Effects and Colors (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the structure for creating custom potions, including their type, custom colors, and specific effects with durations and amplifiers. Alpha values for colors above 255 have no effect. Links to Minecraft wiki for potion types and effects are provided.

```YAML
potion-type: <potion type name>
custom-color:
  ==: Color
  ALPHA: <alpha value>
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>
custom-effects:
- ==: PotionEffect
  effect: <effect type id>
  duration: <duration>
  amplifier: <amplifier>
  ambient: <true|false>
  has-particles: <true|false>
- < ... more potion effects >
```

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

### Prevent Trading with Own Shop - Configuration

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Frequently-Asked-Questions

This configuration option in the Shopkeepers plugin controls whether players can buy items from their own created shops. Disabling this feature can help mitigate potential item duplication bugs. The configuration is typically found in a config.yml file.

```yaml
prevent-trading-with-own-shop: true
# Set to false to allow players to trade with their own shops.
# Default: true
```

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

### Banner Patterns Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the structure for banner patterns, including color and pattern codes. This format is used for specifying custom designs on banners.

```yaml
patterns:
- ==: Pattern
  color: <color name>
  pattern: <pattern code>
- < ... more patterns >
```

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

### Configure Moneynote for Shopkeepers (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

This configuration snippet for the Moneynote plugin disables the glow effect, prevents villager trading rejection, and removes the %signer% from item lore, which is necessary for Moneynote items to function correctly within Shopkeeper trades. It also enables a static UUID for items to prevent trading issues.

```yaml
use-static-uuid:
  enabled: true
  do-not-edit-this: '7d6f11b6-86c4-4c66-891c-9f1ae6a70fdb'
```

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

### Skull Owner Profile Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Details the structure for a skull's owner profile, including unique ID, name, and texture properties. A profile requires either a UUID or a name.

```yaml
skull-owner:
  ==: PlayerProfile
  uniqueId: <profile uuid>
  name: <profile name>
  properties:
  - name: textures
    value: <texture data encoded as base64>
    signature: <signature>
  < ... further properties (unusual) >
```

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

### Confirm Dangerous Actions

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Prompts the player to confirm potentially dangerous actions, such as deleting all shops. This serves as a safeguard against accidental irreversible operations.

```command
/shopkeeper confirm
```

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

### Block Entity Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Specifies the data structure for block entities, primarily defining the block material. The blockMaterial entry can be omitted and is auto-restored.

```yaml
blockMaterial: <item type>
```

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

### Shopkeeper Name Validation Regular Expression

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

Defines a regular expression pattern to validate shopkeeper names. This ensures names meet specific criteria for characters, length, and potentially special characters or color codes.

```regex
"[A-Za-z0-9 ]{3,25}"
```

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

### Enable/Disable Citizen NPC Shops and Related Settings

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

Controls the integration of Citizens NPC shopkeepers. This includes enabling/disabling their creation, setting default NPC types, managing NPC ownership, fluid pushability, interaction cancellation, instant saving, snapshot data saving, and automatic cleanup of invalid shopkeepers.

```config
enable-citizen-shops: true
default-citizen-npc-type: 'PLAYER'
set-citizen-npc-owner-of-player-shops: false
citizen-npc-fluid-pushable: false
cancel-citizen-npc-interactions: true
save-citizen-npcs-instantly: false
snapshots-save-citizen-npc-data: true
delete-invalid-citizen-shopkeepers: false
```

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

### Leather Armor Color Structure (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the color structure for leather armor, using RGBA values. Alpha values beyond 255 have no effect.

```yaml
color:
  ==: Color
  ALPHA: <alpha value>
  RED: <red value>
  GREEN: <green value>
  BLUE: <blue value>
```

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

### Teleport Player to Shopkeeper

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Commands

Teleports a specified player near a shopkeeper. The command attempts to find a safe location and requires the executor to have trading rights for the target shopkeeper. The 'force' argument can override safety checks.

```command
/shopkeeper teleport [player] <shop> ['force']
```

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

### Create Admin Citizens Shopkeeper Command

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Citizens-Shopkeepers

This command creates an admin Citizens shopkeeper. It requires the 'shopkeeper.citizen' permission. The created NPC defaults to a player type.

```text
/shopkeeper npc
```

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

### Configure Axolotl Bucket Variant (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Defines the variant for an axolotl bucket, which dictates the type of axolotl stored within. The variant is represented by an integer. The `internal` data field can hold further entity information.

```YAML
axolotl-variant: <variant integer>
```

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

### Configure Tropical Fish Bucket Variant (YAML)

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Item-Serialization

Specifies the variant for a tropical fish bucket, which determines the appearance and name of the stored fish. The variant is an integer. Additional entity data can be stored in the `internal` field.

```YAML
fish-variant: <variant integer>
```

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

### Inventory Verification Setting in Shopkeepers

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

Controls whether the plugin verifies the player's open inventory type before handling interactions. Disabling this can resolve compatibility issues with certain modded servers but is generally not recommended due to potential unexpected behavior.

```yaml
check-spawn-location-interaction-result: false
disable-inventory-verification: false
```

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

### Shopkeepers Plugin Default Configuration

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

This is a comprehensive default configuration for the Shopkeepers plugin. It includes settings for versioning, debugging options, and other core functionalities. The debugging options allow for granular control over the information logged by the plugin.

```yaml
# *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*
# Shopkeepers Config
# Wiki: https://github.com/Shopkeepers/Shopkeepers-Wiki/wiki/Configuration
# The wiki also explains how item data gets specified inside the config.
# *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*

# Determines the required config migrations. Do not edit manually!
config-version: 9
# Determines the required config item data migrations. Do not edit manually!
data-version: 3839
# The initial debugging state of the plugin.
debug: false
# Additional debugging options.
# - 'log-all-events': Logs all events.
# - 'print-listeners': Prints the registered listeners for the first call of
#    each event.
# - 'shopkeeper-activation': Enables debugging output related to shopkeeper
#    activation.
# - 'regular-tick-activities': Enables debug output for regular shopkeeper
#    activities and behaviors that would otherwise cause debug spam when being
#    enabled by default. This includes for example the activity of teleporting
#    shopkeepers back into place, updating their location when they are mobile
#    and moved around, or behaviors such as the playing of sound effects.
# - 'visualize-shopkeeper-ticks': Visualizes the ticking activities of
#    shopkeepers in-game.
# - 'commands': Enables additional commands related debugging output.
# - 'owner-name-updates': Logs information when updating stored shop owner
#    names.
# - 'item-migrations': Logs whenever a shopkeeper performs item migrations
#    (e.g. for trade offers).
# - 'item-updates': Logs whenever items are updated via the UpdateItemEvent.
# - 'item-conversions': Logs whenever we explicitly convert items to Spigot's
#    data format. Note that this does not log when items get implicitly
#    converted, which may happen under various circumstances.
# - 'empty-trades': Logs detailed item information for the selected trade and
#    the items in the input slots whenever a player clicks an empty trading
#    result slot.
# - 'text-components': Logs additional debug output whenever component-based
#    text is sent.
# - 'unsafe-teleports': Logs additional debug output whenever a teleport is
#    considered unsafe.
debug-options: []
```

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

### Configure Shop Creation Item in Shopkeepers

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

Sets the item used to create player shops and whether to add a custom NBT tag for identification. This allows for future changes to the shop creation item without affecting existing ones. The tag helps in managing shop creation items across different storage and plugin data.

```yaml
shop-creation-item:
  id: 'minecraft:villager_spawn_egg'
  components:
    minecraft:custom_name: '''{"color":"green","italic":false,"text":"Shopkeeper"}'''

add-shop-creation-item-tag: true
identify-shop-creation-item-by-tag: true
```

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

### Configure WorldGuard and Towny Restrictions for Shopkeepers

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Configuration

Manages integration with WorldGuard and Towny plugins to restrict shop placement. It allows disabling WorldGuard flags and enabling Towny commercial area checks. These settings ensure shops are placed according to server-wide zoning rules.

```yaml
require-world-guard-allow-shop-flag: false
register-world-guard-allow-shop-flag: true
enable-towny-restrictions: false
```

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

### Spigot Configuration: Disable Tick Inactive Villagers

Source: https://github.com/shopkeepers/shopkeepers-wiki/wiki/Known-Issues

Configuration setting in Spigot to potentially improve performance by preventing chunks with many villagers from loading indefinitely. It is recommended to disable 'tick-inactive-villagers' if experiencing performance issues related to villager density.

```yaml
tick-inactive-villagers: false
```