Documentation/content/gameplay-systems/shop.en.md

---
title: Shop
type: docs
weight: 5
---

The shop system provides trading and commerce through NPC shops and barter systems.

**Package:** `com.hypixel.hytale.builtin.adventure.shop`

## Architecture

```
ShopPlugin
├── Shop Types
│   ├── ShopAsset - Static shop definitions
│   └── BarterShopAsset - Dynamic barter shops
├── Elements
│   ├── ShopElement - Shop item entry
│   └── ChoiceElement integration
├── Interactions
│   └── GiveItemInteraction
├── Pages
│   ├── ShopPage - Shop UI page
│   ├── ShopPageSupplier
│   └── BarterPage - Barter UI page
└── State
    └── BarterShopState - Persistent barter state
```

## Shop Types

### ShopAsset

Static shops with fixed content:

```java
public class ShopAsset implements JsonAssetWithMap<String, DefaultAssetMap<String, ShopAsset>> {
    protected String id;
    protected ChoiceElement[] elements;  // Shop items

    public String getId();
    public ChoiceElement[] getElements();
}
```

**Asset Location:** `Shops/`

### BarterShopAsset

Dynamic shops with rotating trades:

```java
public class BarterShopAsset implements JsonAssetWithMap<String, DefaultAssetMap<String, BarterShopAsset>> {
    // Barter-based trading with refresh mechanics
}
```

**Asset Location:** `BarterShops/`

## Shop Configuration

### Static Shop Example

```yaml
# Shops/general_store.json
{
  "Id": "general_store",
  "Content": [
    {
      "Type": "ShopElement",
      "Item": "bread",
      "Price": 5,
      "Currency": "gold_coin"
    },
    {
      "Type": "ShopElement",
      "Item": "torch",
      "Price": 2,
      "Currency": "gold_coin"
    }
  ]
}
```

### Barter Shop Components

```java
public class BarterShopState {
    // Persistent state for barter shops
    public static void initialize(Path dataDirectory);
    public static void shutdown();
}

public class TradeSlot { /* Base trade slot */ }
public class FixedTradeSlot extends TradeSlot { /* Fixed trade */ }
public class PoolTradeSlot extends TradeSlot { /* Random from pool */ }
public class WeightedTrade { /* Weighted random trade */ }

public class BarterItemStack { /* Items for barter */ }
public class BarterTrade { /* Complete trade definition */ }
public class RefreshInterval { /* Trade refresh timing */ }
```

## Shop Elements

### ShopElement

Registered as a choice element type:

```java
getCodecRegistry(ChoiceElement.CODEC).register("ShopElement", ShopElement.class, ShopElement.CODEC);
```

## Interactions

### GiveItemInteraction

Choice interaction that gives items to player:

```java
getCodecRegistry(ChoiceInteraction.CODEC).register("GiveItem", GiveItemInteraction.class, GiveItemInteraction.CODEC);
```

## UI Integration

### Shop Page

Custom UI page for shops:

```java
getCodecRegistry(OpenCustomUIInteraction.PAGE_CODEC).register(
    "Shop",
    ShopPageSupplier.class,
    ShopPageSupplier.CODEC
);
```

### Opening a Shop

```yaml
# Interaction definition
{
  "Type": "OpenCustomUI",
  "Page": {
    "Type": "Shop",
    "ShopId": "general_store"
  }
}
```

## API Usage

### Getting Shop Assets

```java
// Get shop asset store
AssetStore<String, ShopAsset, DefaultAssetMap<String, ShopAsset>> store =
    ShopAsset.getAssetStore();

// Get specific shop
ShopAsset shop = ShopAsset.getAssetMap().getAsset("general_store");

// Get barter shop
BarterShopAsset barterShop = BarterShopAsset.getAssetMap().getAsset("traveling_merchant");
```

### Shop Plugin Instance

```java
ShopPlugin shop = ShopPlugin.get();
```

## Barter State Persistence

Barter shop state is saved/loaded automatically:

```java
// Called in start()
BarterShopState.initialize(this.getDataDirectory());

// Called in shutdown()
BarterShopState.shutdown();
```

## Asset Dependencies

Shops load after items:

```java
HytaleAssetStore.builder(ShopAsset.class, new DefaultAssetMap())
    .setPath("Shops")
    .loadsAfter(Item.class)  // Ensure items are loaded first
    .build();
```