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

title, type, weight

title	type	weight
Shop	docs	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:

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:

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

Asset Location: BarterShops/

Shop Configuration

Static Shop Example

# 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

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:

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

Interactions

GiveItemInteraction

Choice interaction that gives items to player:

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

UI Integration

Shop Page

Custom UI page for shops:

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

Opening a Shop

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

API Usage

Getting Shop Assets

// 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

ShopPlugin shop = ShopPlugin.get();

Barter State Persistence

Barter shop state is saved/loaded automatically:

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

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

Asset Dependencies

Shops load after items:

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