Trading and Vendors

This document describes the NPC vendor system, trading rules, and how trading integrates with items, inventory, and interaction in RPG Engine v6.

Overview

The vendor system is built on:

• Dedicated shop NPC classes (BP_RPG_AI_NPC_Shop).
• Item data (BP_ItemData + DTItemData).
• Inventory and money systems (BP_EquipmentComponent, money settings).
• Dialogue and interaction (BP_InteractComponent, dialogue state).
• Save system (BPI_SaveSystem for NPCs and world state).

Trading is always initiated via dialogue; there is no direct “press F to open shop” without going through the dialogue system.

NPC Vendor Classes

Class hierarchy

Vendors are regular AI NPCs with additional shop-specific data:

• BP_RPG_AI
  • Base AI class for all NPCs.
• BP_RPG_AI_NPC
  • Generic NPC with quest/dialogue integration.
• BP_RPG_AI_NPC_Shop
  • NPC with vendor functionality.

Only BP_RPG_AI_NPC_Shop instances are considered vendors.

Vendor configuration

On BP_RPG_AI_NPC_Shop, the following parameters control trading behavior:

• ItemsForSale — array of S_ItemForSale:
  • Item — BP_ItemData for the item being sold.
  • Quantity — integer; how many units this NPC offers.
• Sell Coefficients — TMap<GameplayTag, float>:
  • Key: item type GameplayTag (e.g. ItemType.Weapon, ItemType.Ammo).
  • Value: multiplier applied when the player sells items to this NPC.
  • Higher value → NPC pays more for that item type.
• Buy Coefficients — TMap<GameplayTag, float>:
  • Key: item type GameplayTag.
  • Value: multiplier applied when the player buys from this NPC.
  • Lower value → items are cheaper for this item type.

Base prices come from item data (e.g. in BP_ItemData / related economy assets).
Multipliers per tag allow different vendors to specialize (e.g. weapon dealer vs food vendor).

Opening the Shop

Interaction and dialogue

Trading is triggered via the standard interaction and dialogue systems:

1. The player enters the NPC’s interaction capsule and looks at the NPC Pawn.
2. The player presses IA_Interact.
3. The mediator calls BPI MM QC ActivateDialogueState(Server):
   • Checks that the target has BP_QuestComponentNPC (and other conditions).
   • If successful, activates CharacterStates.UnusualSkills.Dialogue.
4. The PlayerController opens the dialogue UI.
5. One of the dialogue options is “Trade/Shop” (exact text is designer-defined):
   • Selecting this option opens the vendor UI for the current BP_RPG_AI_NPC_Shop.

There is no separate input to directly open the shop; all trading flows through dialogue options.

Vendor UI

The vendor UI:

• Reads ItemsForSale from the current BP_RPG_AI_NPC_Shop.
• Shows player inventory (via BP_EquipmentComponent) and current money.
• Applies Sell Coefficients / Buy Coefficients based on item tags when computing prices.

Implementation details of the shop widget (layout, tabs, etc.) are in the UI docs; this file focuses on data and logic.

Pricing and Currencies

Base item price

Each item has a base price configured in its data (e.g. General Info / Clarification-type DataAsset referenced by BP_ItemData):

• Item registration is in DTItemData:
  • Each row maps an item ID or tag to a BP_ItemData.
• Price fields are typically stored alongside general info (name, description, icon, base cost).

Vendors use these base prices as the starting point before applying coefficients.

Buy and sell price calculation

For a given item:

1. Determine its main item type GameplayTag (e.g. ItemType.Weapon, ItemType.Food).
2. Read base price from item data.
3. When buying from the vendor:
   • Look up the item type tag in Buy Coefficients.
   • If a coefficient exists:
     • Final buy price = base price × coefficient.
   • If not:
     • Final buy price = base price (or default coefficient = 1.0).
4. When selling to the vendor:
   • Look up the item type tag in Sell Coefficients.
   • If a coefficient exists:
     • Final sell price = base price × coefficient.
   • If not:
     • Final sell price = base price (or default coefficient = 1.0).

This model allows:

• Cheap food but expensive weapons at one vendor.
• The opposite at another vendor.
• Special cases (e.g. medical vendor, armor vendor) via tagging and coefficients.

Currency

The core currency logic lives in the money system (see money section of the main settings docs).
At a high level:

• Player money is stored in the character/player-related systems.
• Trading operations:
  • Decrease player money on purchase.
  • Increase player money on sale.
• Money amount is shown in the vendor UI and other UI panels.

If needed, the system can be extended to support multiple currencies by:

• Adding separate money fields for each currency.
• Extending item data to specify which currency it uses.
• Extending vendor logic to support only certain currencies.

Inventory and Items Integration

Trading is tightly integrated with BP_EquipmentComponent and DTItemData.

Buying items

When the player buys an item from BP_RPG_AI_NPC_Shop:

1. Vendor UI checks:
   • Player has enough money.
   • Vendor has enough Quantity for the requested item.
2. If both conditions are met:
   • Money is reduced by the purchase price.
   • The vendor’s ItemsForSale[].Quantity is reduced accordingly.
   • A pickup operation is simulated:
     • BP_EquipmentComponent tries to add the bought items into the inventory grid.
3. If inventory space is limited:
   • BP_EquipmentComponent can apply the same full/partial logic as world pickups:
     • If only part of the requested amount fits, add what fits.
     • Inform the player if some items could not be added (depending on widget implementation).

The shop can either:

• Strictly block purchases if all items cannot fit, or
• Allow partial purchases, depending on the designer’s goals.

Selling items

When the player sells items to a vendor:

1. Player selects item(s) in their inventory.
2. Vendor UI sends a sell request:
   • Determines base price and applicable Sell Coefficients.
   • Computes total payout for the selected quantity.
3. If the sale is allowed:
   • Items are removed from player inventory via BP_EquipmentComponent.
   • Player money is increased by the computed amount.
   • Vendor may:
     • Increase its ItemsForSale stock, or
     • Not track stock for bought items (implementation choice).

Item identity for trading is always based on BP_ItemData and tags, not on world actors.

Save System for Vendors

Vendor state is persisted via BPI_SaveSystem as part of AI save data:

• S_AI_SaveData fields include:
  • Pawn — NPC class.
  • Health — current HP.
  • BT — BehaviorTree.
  • NPC ItemsForSale Data — array of S_ItemForSale:
    • Item — BP_ItemData.
    • Quantity — current quantity.

On save:

• Vendor’s current ItemsForSale array is serialized into NPC ItemsForSale Data.
• Other AI attributes (health, behaviors) are saved alongside.

On load:

• The save system spawns the NPC from the saved Pawn class and transform.
• Restores:
  • Health.
  • BehaviorTree.
  • ItemsForSale quantities from NPC ItemsForSale Data.

This ensures that vendor stock and NPC state remain consistent across sessions.

Interaction and State Integration

The vendor system reuses the same interaction/state architecture as other systems:

• Interaction:
  • BP_InteractComponent detects NPCs via camera trace + interaction capsule.
  • IA_Interact triggers the dialogue activation (BPI MM QC ActivateDialogueState(Server)).
• State system:
  • Dialogues run under CharacterStates.UnusualSkills.Dialogue.
  • Shop UI can be considered part of the dialogue flow (opened from dialogue options).
• Item system:
  • All traded items are defined in DTItemData and described by BP_ItemData.
  • Inventory updates are delegated to BP_EquipmentComponent.

From a project architecture point of view, vendors are just AI actors with extra item arrays and pricing rules plugged into the existing systems.

Related System Docs

Trading and vendors connect to:

• docs/systems/interaction/interaction-and-items.md
• docs/systems/interaction/doors-and-interactables.md