Previous: GUI动作与条件速查.md · Next: 脚本入门.md Related: 自定义GUI.md · 配置文件.md · 经济API.md · 经济插件.md

💰 Economy Actions

This page focuses on the three economy actions available in GUI click actions: give_money (grant currency), take_money (deduct currency), and set_money (set balance). It explains exactly how to write the value, and covers the differences between the Vault / PlayerPoints / ExcellentEconomy backends.

For the basic GUI structure, see 自定义GUI.md. For the global configuration of the economy system, see the economy section in 配置文件.md.

---

🧩 The Three Actions

Action type	Aliases	Purpose
give_money	givemoney	Grant currency to the player
take_money	takemoney,remove_money	Deduct currency from the player (checks balance first; does not deduct if insufficient)
set_money	setmoney	Set the balance directly to a given value

click-actions:
  reward:
    type: give_money
    value: "500"

---

📝 Full value Syntax

Unified format (EconomyActionParser):

[provider:][currency:]amount [| fail message]

Broken down into four parts:

Part	Required?	Description
provider:	Optional	Which economy backend to use: vault / excellenteconomy / playerpoints / auto, with aliases ee / pp
currency:	Depends on backend	Currency type (only ExcellentEconomy needs it)
amount	Required	A number; it is the last segment that can be parsed as a number among all segments
| fail message	Optional	Separated by |; the text shown to the player when the operation fails (supports & codes)

---

🔍 Parsing Rules (follow these and you won't go wrong)

1. First, split the "body" from the "fail message" using |.
2. Then split the body by :; the amount is always the last segment that can be parsed as a number.
3. How prefix segments are recognized:
   • One prefix segment: if it is a known provider (vault/excellenteconomy/playerpoints/auto or the aliases ee/pp), it is treated as the provider; otherwise it is treated as the currency.
   • Two prefix segments: provider:currency.
   • No prefix (just a number): only the amount; provider/currency use their defaults.

📋 Parsing Examples Comparison

value form	provider	currency	amount	fail message
100	default	default	100	—
money:100	default	money	100	—
vault:50	vault	—	50	—
excellenteconomy:gold:100	ee	gold	100	—
100 | Insufficient balance	default	default	100	Insufficient balance
excellenteconomy:money:50 | Not enough gold	ee	money	50	Not enough gold

💡 Note that in vault:50, vault is recognized as the provider, but in money:100, money is not a known provider, so it is treated as the currency. This is exactly the "one prefix segment" decision logic.

---

🔌 Backend Differences (important)

Backend	provider form	currency handling
Vault	vault	Ignores currency
PlayerPoints	playerpoints / pp	Ignores currency
ExcellentEconomy	excellenteconomy / ee	currency must be specified, otherwise it reports CURRENCY_REQUIRED

• Vault / PlayerPoints: single-currency systems. Whether or not you write currency:, it has no effect and is ignored. Just use vault:100 or pp:100.
• ExcellentEconomy: a multi-currency system. You must state which currency, e.g. ee:gold:100. Omitting the currency will fail and report CURRENCY_REQUIRED.

🤖 auto Source Selection

When provider is set to auto (or simply not written), the system automatically selects an available economy backend. This is suitable when you're unsure which economy plugin the server has installed, or when you want the configuration to be portable.

value: "auto:100"        # Automatically select a backend
value: "100"             # Omitting the provider is equivalent to using the default/auto

---

📋 Extensive Usage Examples

# —— Simplest: grant 500 with the default backend ——
reward:
  type: give_money
  value: "500"

# —— Vault: deduct 100 (currency is ignored even if written) ——
pay:
  type: take_money
  value: "vault:100"

# —— PlayerPoints: grant 50 points using the alias pp ——
points:
  type: give_money
  value: "pp:50"

# —— ExcellentEconomy: currency is required ——
buy_gold:
  type: take_money
  value: "ee:gold:100"

# —— ExcellentEconomy full form + fail message ——
buy:
  type: take_money
  value: "excellenteconomy:money:50 | &cNot enough gold, cannot purchase"

# —— Specify only the currency; provider uses the default ——
spend:
  type: take_money
  value: "money:200"

# —— set_money: set the balance directly to 0 ——
reset:
  type: set_money
  value: "0"

# —— auto source selection + fail message ——
gift:
  type: give_money
  value: "auto:1000 | &cGrant failed, please contact an administrator"

---

💬 Fail Messages and Default Messages

The | fail message part is optional; when omitted, each action has a built-in default message. Below is what each action displays in different situations:

Action	Situation	Displayed content
give_money	Grant failed	failMessage or &cFailed to grant currency
take_money	Insufficient balance	Fixed &cInsufficient balance (does not use failMessage)
take_money	Deduction failed (balance sufficient but operation failed)	failMessage or &cFailed to deduct currency
set_money	Set failed	failMessage or &cFailed to set balance
All	Invalid value format	&cInvalid economy action format
All	Economy system unavailable	failMessage or &cEconomy system unavailable

⚠️ Key point: when take_money hits "insufficient balance", it displays the fixed &cInsufficient balance, and the | fail message you wrote will not take effect in that case. Your failMessage is only used when "the balance was sufficient but the actual deduction failed".

---

🩺 Common Errors and Troubleshooting

Symptom	Possible cause	Solution
Shows &cInvalid economy action format	The value is written incorrectly (e.g. the amount segment is missing, or it's all text)	Compare against the syntax table above and make sure there is one segment that can be parsed as a number
Shows CURRENCY_REQUIRED	Used ExcellentEconomy but did not write a currency	Change it to ee:currencyName:amount, e.g. ee:gold:100
Shows &cEconomy system unavailable	The corresponding economy plugin is not installed / the provider name is misspelled	Install the plugin, or use auto, and check the provider spelling
Custom fail message not shown	It's the take_money insufficient-balance case	That case always shows &cInsufficient balance and cannot be overridden; other failures do use failMessage
Written currency has no effect	The backend is Vault / PlayerPoints	They are single-currency, so currency is ignored by design — this is normal
The amount is mistakenly recognized as the currency	The segment order is reversed	The amount must be parseable as a number; arrange prefixes as provider:currency

🔌 provider alias mnemonic: ee = excellenteconomy, pp = playerpoints.

---

📖 Further Reading

• ⚙️ 配置文件.md — the economy configuration section (default provider, toggles)
• 🖼️ 自定义GUI.md — the GUI structure where economy actions live
• 🔎 GUI动作与条件速查.md — pair with the money visibility condition to build purchase buttons
• 🧰 经济API.md — for developers calling the economy interface directly
• 🔗 经济插件.md — integrating Vault / PlayerPoints / ExcellentEconomy