Previous: 方块模型作物.md　·　Next: ../04-开发者/经济API.md Related: ../02-服主指南/经济动作.md · ../04-开发者/经济API.md · ../02-服主指南/配置文件.md

💰 Economy Plugin Integration

QCL uses EconomyBridge to integrate three economy backends in a unified way: Vault, ExcellentEconomy, and PlayerPoints. GUI economy actions and the economy API all go through this layer, so your higher-level config/code doesn't need to care which plugin is installed underneath.

🛟 It also follows the soft-dependency + reflection-bridge pattern: at init it calls registerOptional in order, and only backends that are "installed and enabled" get registered. If a backend isn't installed it's skipped, and it never affects startup.

---

⚖️ Three-Backend Comparison

Dimension	Vault	ExcellentEconomy	PlayerPoints
provider id	vault	excellenteconomy (alias ee)	playerpoints (alias pp)
Currency model	Single currency	Multi-currency (money/gold/silver…)	Single point currency
currency parameter	Ignored	Required on every operation	Ignored
Offline players	✅ Supported	❌ Online only	✅ Supported
Data type	Double	Double	Integer (Double is rounded)
Implementation	Obtains net.milkbowl.vault.economy.Economy via service registration	Reflection on su.nightexpress.excellenteconomy.api.ExcellentEconomyAPI	Reflection on PlayerPoints.getInstance().getAPI()
Recommended use	General-purpose primary currency, best compatibility with other plugins	When you need multiple currencies (gold/silver/points split across accounts)	Pure point/score systems

⚠️ ExcellentEconomy's multi-currency is a double-edged sword: the upside is one plugin managing multiple currencies; the cost is that every balance operation must specify a currencyId (such as money, gold, silver), otherwise it reports CURRENCY_REQUIRED.

⚠️ PlayerPoints is an integer system: any Double passed in is rounded. Don't expect fractional points.

---

🧭 auto Provider-Selection Logic

When economy.default-provider is set to auto (the default), QCL automatically picks a backend using these rules:

Case	Selection priority
currency specified	Prefer ExcellentEconomy (since it's the only one supporting multi-currency)
No currency specified	Vault > ExcellentEconomy > PlayerPoints, returning the first available one

auto + with currency  →  ExcellentEconomy preferred
auto + without currency →  Vault ▶ ExcellentEconomy ▶ PlayerPoints (first available)

💡 Have multiple economy plugins installed and want to force a specific one? Don't use auto; just hard-set default-provider to vault / ee / pp.

---

⚙️ config Configuration

Economy-related config lives in the main config (see ../02-服主指南/配置文件.md):

economy:
  # auto | vault | excellenteconomy(ee) | playerpoints(pp)
  default-provider: auto
  # Default currency id; only meaningful for backends that support multi-currency (ExcellentEconomy)
  default-currency: money

Config key	Values	Description
economy.default-provider	auto / vault / excellenteconomy / ee / playerpoints / pp	Which backend to use; for auto see the rules above
economy.default-currency	currency id (default money)	Used when currency isn't explicitly specified; ignored by single-currency backends

📋 Three Typical Setups

# 1️⃣ Vault only, single currency (most common)
economy:
  default-provider: vault

# 2️⃣ Use ExcellentEconomy's multi-currency, with default currency set to gold
economy:
  default-provider: ee
  default-currency: gold

# 3️⃣ Pure point-currency server
economy:
  default-provider: pp

---

🔧 EconomyProvider Capabilities

Internally each backend implements the EconomyProvider interface, with consistent capabilities:

Method	Purpose
id	Backend identifier (vault / excellenteconomy / playerpoints)
isAvailable	Whether this backend is currently available
getBalance(...)	Query balance
has(...)	Whether there's enough balance
deposit(...)	Deposit
withdraw(...)	Withdraw
setBalance(...)	Set balance directly

All operations return an EconomyTransactionResult:

Field	Meaning
success	Whether it succeeded
message	Human-readable message
code	Result code (e.g. CURRENCY_REQUIRED)
suggestion	Fix suggestion
provider	The backend that actually handled it

For how developers call these methods directly, see 👉 ../04-开发者/经济API.md.

---

🖱️ Relationship to GUI Economy Actions

The economy actions server owners use in the GUI — give_money / take_money / set_money — call the underlying deposit / withdraw / setBalance above. In other words:

GUI action give_money/take_money/set_money
        │
        ▼
   EconomyBridge → selected EconomyProvider → the real economy plugin

For how to write an action's value (amount, currency, etc.), see 👉 ../02-服主指南/经济动作.md.

---

🩺 Diagnostics

For economy-related issues, EconomyDiagnostics gives clear hints:

Diagnostic	Meaning
unavailable()	No economy backend available (none installed/enabled)
providerMissing(id)	The plugin for the provider id you specified isn't installed
currencyMissing(id)	The specified currency id doesn't exist (common with multi-currency backends)

Pair it with /qcl status detail to inspect the economy bridge status.

---

❓ FAQ

Q: Using ExcellentEconomy, operations report CURRENCY_REQUIRED? A: EE is a multi-currency backend, so every operation must carry a currency. Either specify it explicitly in the action/call, or set economy.default-currency to a valid currency (such as money).

Q: Points show decimals / the amounts don't add up? A: PlayerPoints is an integer system, so any Double passed in is rounded. Use Vault/EE if you need to keep decimals.

Q: Giving money to offline players fails? A: ExcellentEconomy only supports online players. To pay offline players, use Vault or PlayerPoints.

Q: I have several economy plugins installed — which one does QCL use? A: In auto mode it follows the priority based on "with or without currency" (see above). To lock it down, hard-set default-provider to a specific id, and use /qcl status detail to confirm the provider actually hit.

Q: What happens if no economy plugin is installed at all? A: No economy backend is registered, and related operations return failure (unavailable()), but it doesn't affect QCL or other features starting up.

---

📚 Further Reading

• 🖱️ ../02-服主指南/经济动作.md — How to write give/take/set_money in the GUI.
• 🧑‍💻 ../04-开发者/经济API.md — Calling EconomyBridge / EconomyProvider in code.
• ⚙️ ../02-服主指南/配置文件.md — Full table of economy.* config options.
• 🧩 概览.md — Overview of external plugin integration.