Quartz 4

guild-potions

2 min read

Potions — Purchase-Triggered XP Buffs

Potions are real drinks (Liquid Death, coffee, etc.) sold at the register that grant short-duration XP buffs. Buy a drink, get a 15–30 minute XP multiplier. Simple, thematic, fun.

Concept

The buff system already exists — BuffDefinitions, ActiveBuffs, multiplicative stacking, timer refresh on re-tap. But buffs currently only trigger from check-ins (NFC, phone, QR). Potions add a purchase trigger: buy a specific item at POS → buff activates automatically.

Flow

Member buys Liquid Death at POS
  → Square webhook (payment.updated) fires
  → existing handler: creates purchase, awards points
  → NEW: check line items against potion-linked buff definitions
  → if match: activate buff on member (15-30 min, 2x XP)

What to Build

  1. New field on BuffDefinitions: squareCatalogItemIds — links a buff to specific Square catalog items. When present, the buff triggers on purchase of those items instead of on check-in.

  2. New trigger method: Add purchase to the trigger methods enum so it’s distinct from check-in-triggered buffs.

  3. Potion activation in Square webhook handler: After creating the purchase record, scan line items → match against any buff definitions with matching catalog item IDs → call activateBuff() for each match.

  4. Seed a test potion: e.g. “Liquid Death” → 2x XP, 15 minutes.

Open Design Questions

  • Stacking (same potion): If someone buys 2 Liquid Deaths in one transaction — refresh timer (current re-tap behavior) or extend duration (15 + 15 = 30 min)?
  • Stacking (different potions): Buy a Liquid Death AND a coffee — multiplicative (2x × 2x = 4x, current buff behavior) or capped? 4x for 15 min is wild but maybe that’s fine.
  • No member linked: If the Square customer isn’t linked to a guild member, skip silently.
  • Duration vs quantity: One fixed duration per buff definition (already how it works), or should buying 2 = longer buff?

Graph View

Backlinks