Skip to content

Ascended hands

Jump to bottom
Oinite edited this page Jun 15, 2026 · 3 revisions

(mechanic from Cryptlib)

Important

Ascended hands must be enabled by adding "ascension_power" to a mod's spectrallib_features table, that is:

SMODS.Mods[mod_id].spectrallib_features = {
  "ascension_power"
}

Ascended hands are poker hands that contain additional cards that still satisfy the poker hand's requirements; each such additional card increases the hand's "ascension power" by 1. For example, given the hand 7S 6H 5C 4D 3S 2H, a 6-long straight, it is considered a Straight (+1).

Ascended hands influence the hand's base chips and mult by applying the following formula to chips and mult separately:

new_value = old_value*(factor^power)

where factor = G.GAME.sunnumber, defaults to 1.25. In Cryptid, this value would be upgraded by Sol.

To allow all cards to contribute to ascension power, the function Spectrallib.has_tether() needs to be hooked to return true. For example, given the hand AS 10H 9C, a High Card, it is considered a High Card (+2).

Usage

All hands have an "ascension threshold", which is one less than the minimum number of cards required for the hand to ascend. They are defined in the global table Spectrallib.ascension_numbers, with keys being poker hand keys, and values being one of the following:

  • number
  • function returning a number or nil - if nil, the hand will not start with any ascension power. The use of Spectrallib.has_tether() may be needed here.

The following functions should be hooked for additional interaction with other mods:

  • Spectrallib.ascension_power_enabled
  • Spectrallib.has_tether
  • Spectrallib.calculate_starting_asc_power
  • Spectrallib.calculate_bonus_asc_power

Localizing ascended hand names

Certain poker hands have their names changed when ascended. For vanilla hands in English (en-us), this includes Five of a Kind -> X of a Kind, and Flush Five -> Flush X, where X is the name of the number of the current ascension power.

As this is dependent on the current ascension power, which is not limited at all, coupled with grammatical differences between languages, functions are required for dynamic localization.

The function G.localization.dynamic.ascended_hand_text(hand_text, scoring_hand) takes the name and contents of the scoring poker hand; it returns a string that is the new name of the poker hand.

Functions

Spectrallib.ascend(value, asc_power) -> number

  • value number
  • asc_power? number

Applies the aforementioned ascension formula to a given value.

Spectrallib.hand_ascension_numbers(hand_name) -> number

  • hand_name string

The returned number is the "ascension threshold" of a hand; it is one less than the minimum number of cards required for the hand to ascend.

Spectrallib.ascension_power_enabled() -> boolean

If returning true, hands can ascend. This is intended to be hooked to enable conditional ascension.

Spectrallib.has_tether() -> boolean

If returning true, all cards count toward ascension power. This function is intended to be hooked to enable conditional tether-mode. (Named after Cryptid's Hyperspace Tether, which enables this effect)

Spectrallib.calculate_starting_asc_power(hand_name, hand_cards, hand_scoring_cards) -> number

  • hand_name - string (hand key)
  • hand_cards - list of Cards (all played cards)
  • hand_scoring_cards - list of Cards (scoring cards)

Gets the starting ascension power of the current hand. This represents the ascension power that is directly based on the current hand. This function is intended to be hook to allow additional sources to add to this value.

Spectrallib.calculate_bonus_asc_power(hand_name, hand_cards, hand_scoring_cards) -> number

  • hand_name - string (hand key)
  • hand_cards - list of Cards (all played cards)
  • hand_scoring_cards - list of Cards (scoring cards)

Gets the bonus ascension power of the current hand. This represents the ascension power that is given by external sources. (Example, Cryptid's EXPLOIT://) This function is intended to be hook to allow additional sources to add to this value.

Hooks

This API hooks the following functions:

  • G.FUNCS.evaluate_round - Reset Chips/Mult colors (changed to gold during hand ascension) at the end of round
  • G.FUNCS.get_poker_hand_info - Display ascended hand information

Clone this wiki locally