Init

content/gameplay-systems/shop.en.md

@@ -0,0 +1,195 @@
+---
+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();
+```