Skip to content

Utility

Jump to bottom
N edited this page Mar 13, 2026 · 24 revisions

Utility functions

Steamodded provides utility functions that extend or replace vanilla functionality or provide other useful tools you may need when making your mod. This page contains information on these functions. Check out src/utils.lua if you'd like to learn more about a function's implementation.

Debugging

inspect(table) -> string

Given an input table, outputs a shallow mapping of keys to values as a string. Gives no further information on subtables.

inspectDepth(table) -> string

Given an input table, recursively creates a string representation up to a depth of 5.

inspectFunction(func) -> string

Given an input function, outputs details on its name, source, line of definition and number of upvalues.

serialize(t, indent) -> string

Given an input table, creates a string containing Lua code that evaluates to the serializable part of t. Information may be lost, and circular references are not resolved.

serialize_string(s) -> string

Serializes the provided string.

tprint(t, indent) -> string

Recursively stringifies an input table into pseudo-valid Lua code, leaving non-serializable values and tables above a depth of 5 into their default string representations.

SMODS.deepfind(tbl, val, mode, immediate) -> table

Searches for provided val anywhere deep within the provided tbl. Returns a table of finds. mode - "index"/"i" will have val compared to the indexes in the tables. "value"/"v" will have val compared to the values in the tables. immediate - Will return immediately after finding the value the first time.

SMODS.debug_calculation()

Enables debugging of Joker calculations. Every time that Card:calculate_joker() is called, G.contexts is updated for every value within context.

Number Formatting

round_number(num, precision) -> number

Rounds the input number to a given amount of decimal places.

format_ui_value(value) -> string

Stringifies the input if it is not a number. Otherwise return the number as it should be displayed in the UI (e.g. scientific notation).

Randomness

SMODS.poll_rarity(_pool_key, _rand_key) -> string|number

Generates a random rarity for the given pool (the only vanilla pool that supports rarities is 'Joker'). If _rand_key is present, use it as a seed.

SMODS.poll_seal(args) -> string?

Checks if a seal should be generated, and generates one according to the specified arguments if so. The following arguments are supported:

  • key - Randomness seed for the check whether to generate a seal, defaults to 'stdseal'.
  • mod - Multiplier to the base rate at which seals appear.
  • guaranteed - If this is true, always generate a seal.
  • options - A table of possible seals to generate. Defaults to all available seals.
  • type_key - Randomness seed for the roll which seal to generate.

SMODS.poll_enhancement(args) -> string?

Checks if an enhancement should be generated, and generates one according to the specified arguments if so. The following arguments are supported:

  • key - Randomness seed for the check whether to generate an enhancement, defaults to 'std_enhance'.
  • mod - Multiplier to the base rate at which enhancements appear.
  • guaranteed - If this is true, always generate an enhancement.
  • options - A table of possible enhancements to generate. Defaults to all available enhancements.
  • type_key - Randomness seed for the roll which enhancement to generate.

SMODS.poll_edition(args) -> string?

  • Checks if an edition should be generated, and generates one according to the specified arguments if so. The following arguments are supported:
    • key - Randomness seed for the check whether to generate an edition, defaults to 'edition_generic'.
    • mod - Multiplier to the base rate at which editions appear.
    • no_negative - Disables negative edition chance (chance is added to polychrome)
    • guaranteed - If this is true, disables base card and always generates an edition.
    • options - A table of possible editions to generate. Defaults to all editions marked in_shop.

Mod-facing Utilities

These functions facilitate specific tasks that many mods may use but may be harder to achieve when implemented individually. Some replace base game functions to create a more usable interface.

SMODS.find_mod(id) -> table

Returns a list of mods that either match the given mod ID or provide it, and are enabled and loaded. The result of next(SMODS.find_mod(id)) can be used to determine if a mod is present, akin to finding cards with SMODS.find_card.

SMODS.load_file(path, id) -> function

Given a path to a file in the context of the mod currently being loaded, loads the file contents and returns them as a function. If this function is called after the mod loading stage, a mod's id must be specified in order to find the correct file. Return type is the same as love.filesystem.load and loadfile.

  • Example usage: assert(SMODS.load_file('jokers.lua'))()

SMODS.juice_up_blind()

Plays a 'juice up' animation on the Blind chip.

SMODS.change_base(card, suit, rank) -> Card?, string?

Given a Card representing a playing card, changes the card's suit, rank, or both. Either argument may be omitted to retain the original suit or rank. This function returns nil if it fails, with the second argument being a string with an error message. It is recommended to always wrap calls to it in assert so errors don't go unnoticed.

  • Examples: assert(SMODS.change_base(card, 'Hearts')) converts a card into Hearts. assert(SMODS.change_base(card, nil, 'Ace')) converts a card into an Ace. assert(SMODS.change_base(card, 'Hearts', 'Ace')) converts a card into an Ace of Hearts.

SMODS.modify_rank(card, amount) -> Card?, string?

Given a Card representing a playing card, increases or decreases the card's rank by the specified amount. The rank is increased if amount is positive and decreased if it is negative. This function returns nil if it fails, with the second argument being a string with an error message. It is recommended to always wrap calls to it in assert so errors don't go unnoticed.

  • Examples: assert(SMODS.modify_rank(card, 1)) increases a card's rank by one, like the Strength Tarot. assert(SMODS.modify_rank(card, -2)) decreases a card's rank by two.

SMODS.find_card(key, count_debuffed) -> table

This function replaces find_joker. It operates using keys instead of names, which avoids overlap between mods. Returns an array of all jokers or consumables in the player's possession with the given key. Debuffed cards count only if count_debuffed is true.

SMODS.add_card(t) -> Card

This function replaces add_joker. It takes the same input parameters as SMODS.create_card (below) and additionally emplaces the generated card into its area and evaluates add_to_deck effects.

SMODS.create_card(t) -> Card

This function replaces create_card. It provides a cleaner interface to the same functionality. The argument to this function should always be a table. The following fields are supported:

  • set - The card type to be generated, e.g. 'Joker', 'Tarot', 'Spectral'
    • 'Playing Card' can be used for a random pick between 'Base' and 'Enhanced'.
  • area - The card area this will be emplaced into, e.g. G.jokers, G.consumeables. Default values are determined based on set.
  • legendary - Set this to true to generate a card of Legendary rarity.
  • rarity - If this is specified, skip rarity polling and use this instead of a chance roll between 0 and 1.
    • Under vanilla conditions, values up to 0.7 indicate "Common" rarity, values above 0.7 and up to 0.95 indicate "Uncommon" rarity, and values above 0.95 indicate "Rare" rarity.
    • This can also be the key of a modded rarity or 'Common', 'Uncommon', 'Rare' or 'Legendary' for vanilla rarities.
  • skip_materialize - If this is true, a start_materialize animation will not be shown.
  • soulable - If this is true, hidden Soul-type cards are allowed to replace the generated card. Usually, this is the case for cards generated for booster packs.
  • key - If this is specified, generate a card with the given key instead of the random one.
  • key_append - An additional RNG seeding string. This should be used to put different sources of card generation on different queues.
  • no_edition - If this is true, the generated card is guaranteed to have no randomly generated edition.
  • edition, enhancement, seal - Applies the specified modifier to the card.
  • stickers, force_stickers - This should be an array of sticker keys. Applies all specified stickers to the card. force_stickers bypasses all checks.
  • front - Front of the playing card, takes the playing card's key (e.g. H_A). Ignores rank and suit.
  • rank - Rank of the playing card. Can be the key or the card_key (e.g. 'Ace' or 'A').
  • suit - Suit of the playing card. Can be the key or the card_key (e.g. 'Hearts' or 'H').
  • enhanced_poll - Chance to pick 'Base' over 'Enhanced' with set 'Playing Card'. Default: 0.6
  • allow_duplicates - Allows duplicates of created cards (when a key is not specified) as if Showman was owned.

SMODS.debuff_card(card, debuff, source)

Allows manually setting and removing debuffs from cards.

  • source should be a unique identifier string. You must use the same source to remove a previously set debuff.
  • If debuff is the string 'prevent_debuff', blocks all possible debuffs on the card until removed.
  • If debuff is another truthy value, set a debuff on the card.
  • If debuff is a falsy values, remove this debuff.

SMODS.recalc_debuff(card)

Recalculates the debuff state of a card.

SMODS.merge_lists(...) -> table

Takes any number of 2D arrays. Flattens the input into a 1D array that contains all elements once in the order they first appear and removes any duplicates. This can be used to merge results from poker hand evaluation to create a combined hand.

SMODS.get_blind_amount(ante) -> number

Provides score requirements for higher stages of ante scaling. If you want to implement your own scaling rules, you should modify this function.

SMODS.stake_from_index(index) -> string

Given an index from the Stake pool, return the corresponding key, or 'error' if it doesn't exist.

SMODS.upgrade_poker_hands(args)

(Added in 1221a) This function levels up or upgrades poker hands. This allows permanent modifications to the chips and mult (and other parameters if defined) for each poker hand that will not be removed when a standard level up happens. The argument to this function should always be a table. The following fields are supported:

  • hands : table of strings or a single string of hand names to level up (if left blank defaults to all Poker Hands)
  • parameters : table of strings of keys of Scoring_Parameters to upgrade (if left blank defaults to all Scoring Parameters)
  • level_up : increases the level of the hand by amount passed (NOTE: this can be used to level up a hand by more than one level)
  • func : pass a custom function function(current, base, parameter) for custom modifications to the parameters in a Poker Hand (if left blank defaults to normal level up method)
  • from : the Object that is doing the upgrading, will juice_up during animations
  • instant : boolean that disables animations

SMODS.smart_level_up_hand(card, hand, instant, amount)

DEPRECATED IN 1221a IN FAVOR OF SMODS.upgrade_poker_hands(args)

Akin to vanilla's level_up_hand(), but avoids uneccessary calling of update_hand_text()

  • card - If included, juices up this card during the animation
  • hand - Key to the hand being leveled up.
  • instant - Skips the level up animations.
  • amount - How much the poker hand is leveled. Defaults to 1.

SMODS.blueprint_effect(copier, copied_card, context) -> table?

Helper function to copy the ability of another joker, akin to Blueprint/Brainstorm.

  • copier is the card the will be copying the effect of copied_card, using the provided context table.
  • The returned table is the calculated effect of copied_card, with the display card set to copier.
  • Example: 
    calculate = function(self, card, context)
    -- This is an implementation of Brainstorm
    local other_joker = G.jokers.cards[1]
    local other_joker_ret = SMODS.blueprint_effect(other_joker, card, context)

    if other_joker_ret then
        return other_joker_ret
    end
end

SMODS.merge_effects(...) -> table

Takes any number of 2D arrays. Flattens given calculation returns into one, utilising extra tables.

  • This can be used to merge returns from SMODS.blueprint_effect.

SMODS.has_enhancement(card, key) -> bool

Returns true if the provided card has a specific enhancement.

SMODS.is_eternal(card, trigger) -> bool

Returns true if the card is cosidered to be "eternal" (cannot be destroyed).

  • card - the card that is being checked
  • trigger - generally should be a reference to the object that is doing the check. If the check is being done by a general function, it is recommended to supply an identifying table such as {destroying_cards = true}

SMODS.shallow_copy(t) -> table

Returns a shallow copy of the provided table.

time(func, ...) -> number

Calls an input function with any given additional arguments: func(...) and returns the time the function took to execute in milliseconds. The return value from func is lost.

SMODS.destroy_cards(cards, bypass_eternal, immediate, skip_anim)

Destroys any type of cards given to the function appropriately, with respect to further calculations if called during the scoring loop.

  • cards - Can be an individual Card object, or a table of Card objects.
  • bypass_eternal - Destroys cards even if they're Eternal.
  • immediate - Destroys the cards immediately not creating an event (Note: Card.start_dissolve and Card.shatter internally still create an event)
  • skip_anim - Skips the normal animation and changes it to that of food jokers.

SMODS.add_voucher_to_shop(key)/SMODS.add_booster_to_shop(key)

Adds a Voucher or a Booster to the current shop.

  • key - the key of the object to be added. If no key is provided, the next seeded object will be used

SMODS.change_voucher_limit(mod)/SMODS.change_booster_limit(mod)

Modify the number of Voucher/Booster objects that appear in the shop

  • mod - number to change limit by (if this limit is increased whilst in a shop, a new object will be created automatically)

SMODS.change_free_rerolls(mod)

Modify the number of free rerolls per shop

  • mod - number to change the amount by (applies instantly if within a shop)

SMODS.change_play_limit(mod)/SMODS.change_discard_limit(mod)

Used to change the number of cards that can be played/discarded at one time. Play limit has a lower limit of 1, and discard has a lower limit of 0. (Note: values can go below these limits, but will have no effect)

  • mod - number to change the limit by

SMODS.draw_cards(hand_space)

Function to draw a certain number of cards to hand, calling the relevant calculation contexts

  • hand_space - the number of cards to draw

SMODS.is_poker_hand_visible(handname) -> boolean

This function checks whether a poker hand is visible in the poker hands menu.

  • handname - string of poker hand name (Calls to get_current_pool will add an args table of {source = _append} where _append is the 4th argument of get_current_pool)

SMODS.create_sprite(x, y, width, height, atlas_key, pos) -> Sprite|AnimatedSprite

(Added in 1221a) Handles creation of Sprite objects with the correct atlas type.

SMODS.is_active_blind(key, ignore_disabled) -> boolean

(Added in 1221a) Returns true when the current blind matches the inputted key.

SMODS.get_clean_pool(_type, _rarity, _legendary, _append)

(Added in 1501a) Wrapper for get_current_pool that will exclude any "UNAVAILABLE" values in the pool, therefore giving a list of valid keys only.

SMODS.size_of_pool(pool) -> integer

Returns the number of valid keys in a pool obtained with get_current_pool.

Joker Effects

SMODS.smeared_check(card, suit) -> boolean

Checks if the base suit of card counts as suit for effects similar to Smeared Joker.

SMODS.seeing_double_check(hand, suit) -> boolean

Checks if hand fulfills the conditions for Seeing Double but for suit.

SMODS.showman(card_key) -> boolean

Checks if card_key can spawn even if the player has duplicates for effects similar to Showman.

SMODS.four_fingers(hand_type) -> number

Returns how many cards are necessary to make a Flush or a Straight for effects similar to Four Fingers. hand_type will be flush or straight.

SMODS.shortcut() -> boolean

Checks if the effects of Shortcut are applying (i.e. if Straights can be made with gaps of one rank).

SMODS.wrap_around_straight() -> boolean

Returns true if Straights can wrap around.

Card Methods

Card:should_hide_front() -> boolean

This function checks whether a card object should display the front sprite or not. Currently only checks for Stone cards and cards with overrides_base_rank = true defined on the Center, but can be hooked to provide additional functionality as required.

Card:is_rarity(rarity) -> boolean

This function checks if a Joker is a certain rarity. Accepts a number for vanilla rarities, or a key as a string for modded rarities.

Card:can_calculate(ignore_debuff, ignore_sliced) -> boolean

This function checks whether a card can run its calculate function.

Game Objects

Guides

Release Notes

Found an issue, or want to add something? Submit a PR to the Wiki repo.

Clone this wiki locally