Shop System

Learn how to use and customize the shop UI system with buy/sell functionality.

Overview

The shop system consists of two main components:

• ShopScreen.tsx - Main shop container and state management

• ShopTradeList.tsx - Item list with quantity controls

Shop Screen Structure

┌─────────────────────────────────────┐
│  Shop Screen                        │
├───────┬─────────────────────────────┤
│ Buy   │ Item List                   │
│>Sell  │ ┌─────────────────────────┐ │
│ Leave │ │ Potion    Have:5  Qty:1 │ │
│       │ │ Hi-Potion Have:2  Qty:1 │ │
│       │ └─────────────────────────┘ │
│ Gold  │ Description: Restores HP    │
│ 1000G │ Stats: (equip changes)      │
└───────┴─────────────────────────────┘

Basic Usage

Opening a Shop

From RMMZ events, the shop command automatically triggers ShopScreen:

// Shop Processing event command works automatically
// Or manually:
SceneManager.push(Scene_Shop);
SceneManager.prepareNextScene([goods], purchaseOnly);

Component Structure

const ShopScreen: React.FC<BaseMenuScreenProps> = (props) => {
  // Three states: Action, Buy, Sell, Confirm
  const [currentState, setCurrentState] = useState(ShopState.Action);

  // Track selected item and quantities
  const [selectedItem, setSelectedItem] = useState(null);
  const [quantities, setQuantities] = useState({});

  return (
    <div className="shop-screen">
      {/* Left: Action menu */}
      <Chooser items={shopActions} onItemSelected={...} />

      {/* Right: Trade list */}
      <ShopTradeList
        mode={displayMode}
        items={displayMode === 'buy' ? buyItems : sellItems}
        hasFocus={currentState === ShopState.Buy || currentState === ShopState.Sell}
        onActivate={handlePurchase}
        {...quantityProps}
      />
    </div>
  );
};

Buy/Sell Mode Switching

The shop shows different item lists based on mode:

// Buy mode: shows shop goods
const buyItems = useMemo(() => {
  return shopGoods
    .map((g) => props.pageData.shopData.goodsToItem(g))
    .filter((x) => !!x);
}, [shopGoods]);

// Sell mode: shows player inventory (excluding key items)
const sellItems = useMemo(() => {
  const gp = props.pageData.runtime.gameParty;
  return [
    ...gp.items(),
    ...gp.weapons(),
    ...gp.armors(),
  ]
    .filter((it) => (gp.numItems(it) || 0) > 0)
    .filter((it) => it?.itypeId !== 2); // No key items
}, [props.pageData.runtime.gameParty, goldData]);

Important: Use useMemo to prevent recreating the array every render, which would break Chooser selection.

Quantity Management

Quantities are tracked per-item using a keyed state object:

// Key format: "i:1" (item), "w:5" (weapon), "a:2" (armor)
const keyFor = (obj) => {
  const fam = obj.wtypeId != null ? 'w' :
              (obj.atypeId != null || obj.etypeId != null) ? 'a' : 'i';
  return `${fam}:${obj.id}`;
};

// State
const [quantities, setQuantities] = useState<Record<string, number>>({});

// Getters/setters
const getQty = (obj) => quantities[keyFor(obj)] ?? 1;
const incQty = (obj) => setQuantities(prev => ({
  ...prev,
  [keyFor(obj)]: (prev[keyFor(obj)] ?? 1) + 1
}));

Sell Confirmation

When selling, show a confirmation dialog:

// State for pending sell
const [pendingSellItem, setPendingSellItem] = useState(null);
const [pendingSellQty, setPendingSellQty] = useState(0);

// On sell activation
if (displayMode === 'sell') {
  setPendingSellItem(it);
  setPendingSellQty(liveQty);
  setCurrentState(ShopState.Confirm);
}

// Render confirm dialog
{currentState === ShopState.Confirm && pendingSellItem && (
  <div className="confirm-dialog">
    <div>
      Sell {pendingSellQty}x {pendingSellItem.name} for {sellPrice}G?
    </div>
    <Chooser
      items={[
        { name: "Yes", action: () => executeSell() },
        { name: "No", action: () => cancelSell() }
      ]}
      hasFocus={true}
      onItemSelected={(item) => item.action()}
    >
      {(item, selected) => (
        <div className={selected ? "selected" : ""}>{item.name}</div>
      )}
    </Chooser>
  </div>
)}

Equipment Stats Preview

For weapons/armor, show stat changes:

function getEquipParamChanges(partyMember, index, item) {
  const actorCopy = partyActorsCopies[index];

  // Get stats BEFORE equipping
  const before = Array.from({ length: 8 }, (_, pid) =>
    Math.floor(partyMember.param(pid))
  );

  // Find equip slot and force-equip on copy
  const slots = actorCopy.equipSlots();
  const want = item.wtypeId ? 1 : item.etypeId;
  let slotId = slots.findIndex((t) => t === want);

  if (slotId >= 0) {
    actorCopy.forceChangeEquip(slotId, item);
  }

  // Get stats AFTER equipping
  const after = Array.from({ length: 8 }, (_, pid) =>
    Math.floor(actorCopy.param(pid))
  );

  // Return changes
  return before.map((val, pid) => ({
    id: pid,
    before: val,
    after: after[pid],
  })).filter((p) => p.before !== p.after || item.params[p.id] !== 0);
}

// Render
{equipParamChanges.map((param) => {
  const better = param.after > param.before;
  const color = better ? '#00ff00' : '#ff3333';
  return (
    <div>
      {statNames[param.id]}: {param.before} →
      <span style={{ color }}>{param.after}</span>
    </div>
  );
})}

Price Calculation

// Buy price: item.price
const buyPrice = item.price || 0;

// Sell price: half of buy price
const sellPrice = Math.floor((item.price || 0) / 2);

// Total for quantity
const total = price * quantity;

Disabling Options

Disable Continue when no save files:

// Check if action allowed
const canBuy = (item, qty) => {
  const cost = (item.price || 0) * qty;
  return qty > 0 && props.pageData.runtime.gameParty.gold() >= cost;
};

const canSell = (item, qty) => {
  const have = props.pageData.runtime.gameParty.numItems(item) || 0;
  return qty > 0 && qty <= have && item.itypeId !== 2; // Not key item
};

// In ShopTradeList
<div className={allowed ? '' : 'opacity-60'} aria-disabled={!allowed}>
  {/* item display */}
</div>

Customization Examples

Custom Shop Theme

.shop-screen {
  background: url('/img/shop-bg.png');
  color: #fff;
}

.shop-trade-list-item.selected {
  background: linear-gradient(90deg, #ff6b6b, #ff8e53);
}

Adding Shop Keeper Dialog

const ShopScreen = (props) => {
  const [showGreeting, setShowGreeting] = useState(true);

  return (
    <div>
      {showGreeting && (
        <BaseModal show={true} onHide={() => setShowGreeting(false)}>
          <div>Welcome to my shop!</div>
          <button onClick={() => setShowGreeting(false)}>Start Shopping</button>
        </BaseModal>
      )}
      {/* Rest of shop UI */}
    </div>
  );
};

Discounts/Sales

// Apply discount to buy prices
const getUnitPrice = (item) => {
  const basePrice = displayMode === 'buy' ? item.price : Math.floor(item.price / 2);
  const discount = isOnSale(item) ? 0.8 : 1.0;
  return Math.floor(basePrice * discount);
};

// Show sale badge
{isOnSale(item) && (
  <span className="sale-badge">20% OFF!</span>
)}

Common Issues

Selection doesn't work in sell mode

Cause: sellItems array recreated every render

Fix: Wrap in useMemo:

const sellItems = useMemo(() => {
  /* calculation */
}, [dependencies]);

Quantity resets when switching items

Cause: Quantity state not persisted per-item

Fix: Use keyed quantities object as shown above

Equipment preview shows wrong stats

Cause: Modifying live actor instead of copy

Fix: Create actor copy first:

const actorCopy = props.pageData.shopData.createActorCopy(actor);
actorCopy.forceChangeEquip(slotId, item);
// Read stats from copy, not original

See Also

• Chooser Component

• State Management

• Components Reference