How to use this API

Make sure to add the latest version of Wallet as a dependency to your mod. In your mod's metadata json file, add "Wallet (>=1.3.1)" to the list of dependencies. If your mod is on Thunderstore, you should also add "ThunderEdge-Wallet-1.3.1" as a dependency in your manifest.json file. Once you've finished that, you can initialize a currency as follows:

Wallet.Currency({
	key = "your_currency"
})

After that, a currency easing function and a few variables will automatically be initialized for you.

ease_modprefix_your_currency(mod, instant) -- Works exactly like ease_dollars but for your own currency
G.GAME.modprefix_your_currency -- The current amount of your own currency
G.GAME.modprefix_your_currency_buffer -- Similar to G.GAME.dollar_buffer and other buffers 
G.GAME.modprefix_your_currency_bankrupt_at

Note

If you use an LSP (Language Server Protocol) for Balatro modding, your LSP will not recognize functions generated by this mod and it will tell you that these functions are undefined globals, even though they are defined. To fix this, add the following annotations to a separate file for LSP definitions.

---@param mod number
---@param instant? boolean
function ease_modprefix_your_currency(mod, instant) end

As a reminder, this file should NEVER be loaded.

With this mod installed, hovering over the amount of money you have with your cursor will show each of your currencies in a popup above your current money amount.

In addition, this mod also automatically handles calculation returns for currencies initialized with this mod. Return modprefix_your_currency = amount from a calculate function to give the player that much of your currency. You can also give permanent bonuses for your currency to playing cards by setting the following values on a playing card.

card.ability.perma_p_modprefix_your_currency -- Gives currency when scored
card.ability.perma_h_modprefix_your_currency -- Gives currency when held in hand at end of round

Warning

In order for these permanent bonuses to show up correctly on playing cards, you will have to add some entries to your localization file. See this if you need help setting up a localization file. Inside descriptions.Other, add the following entries:

p_modprefix_your_currency = {
	text = {
		-- your text here
		-- #1# here corresponds to card.ability.perma_p_modprefix_your_currency
	}
},
h_modprefix_your_currency = {
	text = {
		-- your text here
		-- #1# here corresponds to card.ability.perma_h_modprefix_your_currency
	}
}

You can also make a center in the shop cost a custom currency by adding currency_cost = key to the center. key must be the full key of a currency, including the mod prefix.

In addition, you may define a calc_currency_bonus function on any object that supports calc_dollar_bonus. On a Joker, this function should look something like this:

calc_currency_bonus = function(self, card)
	return {
		modprefix_your_currency = amount,
		modprefix_another_currency = amount,
	}
end

Like with calc_dollar_bonus, you can customize the cashout text.

calc_currency_bonus = function(self, card)
	return {
		modprefix_your_currency = {
			amount, 
			{
				text = "Your Text Here",
				text_colour = G.C.BLUE,
			}
		}
	}
end

Utility Functions

Wallet.mod_buffer(currency: string, amt: number)

Safely adds amt to the given currency's buffer. currency must be a full key of an existing currency, including the mod prefix.

Wallet.mod_dollars_buffer(amt: number)

Safely adds amt to G.GAME.dollar_buffer.

Wallet.reset_buffer(currency: string)

With the correct timing, resets the given currency's buffer to 0. currency must be a full key of an existing currency, including the mod prefix.

Wallet.reset_dollars_buffer()

With the correct timing, resets G.GAME.dollar_buffer to 0.

Wallet.reset_buffers(...: string)

Simultaneously resets the given currencies' buffers to 0. Each argument passed into this function must be a full key of an existing currency, including the mod prefix.

Important

Handling buffers correctly in a calculation return with the above methods should look something like this:

local amt = card.config.extra.your_currency
Wallet.mod_buffer("modprefix_your_currency", amt)
return {
	modprefix_your_currency = amt,
	func = function()
  		Wallet.reset_buffer("modprefix_your_currency")
	end
}

Note the lack of an event in the func return. All of Wallet's reset buffer methods automatically add the event to reduce boilerplate.

The following function is for use with a custom calc_cost defined in your currency object.

Wallet.get_edition_extra_cost(card: Card) -> number

Returns the cost modifier of the given card's edition, if it has one. Otherwise, returns 0.

Wallet.Currency

This class has no class prefix.

• Required Parameters:
  • key
• Optional Parameters
  • font = nil Set this to the full key of a font to have this currency's symbol use a particular font.
  • starting_amount = 0 How much of this currency you start runs with.
  • colour = G.C.MONEY The primary colour associated with this currency.
  • decrease_colour = G.C.RED The colour associated with decreases in this currency.
  • currency_prefix = "$" Goes before the number whenever this currency is displayed.
  • currency_suffix = "" Goes after the number whenever this currency is displayed.
  • currency_label = nil Set to a localization key within misc.dictionary to have the corresponding text appear the suffix whenever this currency is displayed. Useful when you don't have a dedicated symbol for your currency.
  • sfx_key = "coin1" The sound effect played after any changes in this currency.
  • scoring_sfx_key = "coin3" This sound effect played after any changes in this currency as a result of calculation.
  • echo_sfx_key = "coin6" This sound effect is played during cashout and is intended to have a more echo-y effect.
  • no_ui = nil (ADVANCED) If set to true, will prevent this currency from showing up when hovering over your dollars. You should define your own visuals if this is set to true.
  • cashout_always_number = nil If set to true, any time this currency appears in cashout, the amount will always be displayed with a number instead of individually displaying the symbol that represents the currency if the amount of currency does not exceed a certain threshold.

Methods

pre_ease_func(self: Wallet.Currency, mod: number, instant: boolean) -> number?

• Return a number to preemptively modify the change in the currency.

post_ease_func(self: Wallet.Currency, mod: number, instant: boolean)

• Use this to add your own contexts related to changes in your currency.

custom_ease_func(self: Wallet.Currency, mod: number)

• (ADVANCED) Define this to manually control the animations associated with changes in this currency.

calc_cost(self: Wallet.Currency, card: Card, base_cost: number): number?

• Calculate any changes to a card's currency cost here. The card's cost will be set to the returned value, or base_cost if no value is returned from this function.