Library-wide refactor

[Oinite12]

This pull request refactors, uh, pretty much everything. The goal of this project is to improve the readability and navigability of the entire library, so that other developers have an incentive to use this library or at least introduce cross-mod compatibility. This scope may have been stepped over a few times, but I tried to hold back from entire reworks - at least until I finish this preliminary refactor.

I would say that this refactor covers 90% of the library and is 90% complete. There are several things that I've glossed over (particularly UI code (not really sure how to go about cleaning it)), and despite my best efforts, there are some functions that I simply do not understand and thus am unable to annotate/document. I've marked trouble points with "todo", which can be easily searched for across the repository; help in those areas would be greatly appreciated.

I tried to make sure that function behaviours don't change, but there may be some oversights on my end. Unfortunately I don't really have a good way to debug these functions, so if anyone is able to do some bug-hunting, that would be appreciated. Additionally, despite trying to preserve function behaviors, this whole project is still drastic in its changes, hence my fork and this PR.

(I also wrote some wiki pages, but that documentation is only reflective of this fork/PR, so I'd rather not share it unless this PR is accepted. If it isn't accepted, I can still publish the wiki pages but I'll have to do some rewrites to reflect the current library.)

The following changes have been made:

• A large majority of code has been moved around to simplify logic, improve readability, and group related functions together for better navigability.
  • A large majority of functions have annotations for documentation.
    • The file Spectrallib/lspdef.d.lua has been created to extend existing SMODS classes/annotations.
  • Regions (#regions) have also been added in especially large files.
• A large majority of variables are renamed to be more descriptive.
• The subdirectory "Spectrallib" has been created to hold Spectrallib-original APIs.
• Modular design is introduced in the following APIs, which currently have hard-coded behaviours:
  • Ascended Hands
    • Spectrallib.ascension_numbers holds numbers or number-valued functions describing how many cards are needed for ascension.
  • Value Manipulation
    • Spectrallib.manipulate_types defines behaviours for the manipulation types "+", "X", "^", and "hyper". It also allows the definition of new types.
  • Forcetrigger
    • Spectrallib.vanilla_forcetrigger_results holds definitions for vanilla Joker forcetrigger effects.
  • Voucher Unredeeming
    • Spectrallib.vanilla_unapply_results holds definitions for vanilla voucher unredeeming effects.
  • Deck Redeeming
    • Spectrallib.deck_config_apply_effects defines how specific deck config keys should be interpreted. It also allows the definition of modded config keys.
• Most cross-mod compatibility code has been decoupled from "vanilla" behaviors and moved into the "compat" subdirectory; hopefully this should be the start of making the library a bit more mod-agnostic:
  • Cryptid
    • Hook G.FUNCS.cry_asc_UI_set (EXPLOIT:// changing color of Ascension Power)
    • Hook Spectrallib.has_tether (Actually use Hyperspace Tether)
    • Hook G.FUNCS.get_poker_hand_info (Clusterwark special name)
    • Hook Spectrallib.calculate_starting_asc_power (Extra starting Ascension Power for DECLARE:// hands)
    • Hook Spectrallib.calculate_bonus_asc_power (Bonus Ascension Power from EXPLOT://, and Sol/Perkele under Observatory)
    • Entries in Spectrallib.ascension_numbers (for Cryptid poker hands)
    • Hook Spectrallib.ascension_power_enabled (Contentset-activated Ascended Hands)
    • An entry in Spectrallib.deck_config_apply_effects (for config.cry_beta)
  • Entropy
    • Redirect Entropy.get_highlighted_cards = Spectrallib.get_highlighted_cards
    • Redirect Entropy.blind_is = Spectrallib.blind_is
    • Hook Spectrallib.calculate_ascension_modification (Axeh's effect)
    • Hook SMODS.upgrade_poker_hands (Strawberry Pie's effect)
  • Hot Potato
    • An entry in Spectrallib.deck_config_apply_effects (for config.plincoins)
  • Infinite Fusion
    • Hook Card:no (Fusion components also checked for "no_"..key)
  • Bunco
    • Entries in Spectrallib.ascension_numbers (for Bunco poker hands)
  • Spectrum API
    • Entries in Spectrallib.ascension_numbers (for Spectrum API poker hands)
• The following functions have been added:
  • G.localization.dynamic.ascended_hand_text(hand_text, scoring_hand) - Unique to each localization that defines this function, this function describes how to change the names of poker hands that have been ascended (like that Flush Five, Flush Six, Flush Seven etc. type of thing).
    • In general, the dynamic subtable of the localization table might be useful for localization-specific dynamic text.
  • Spectrallib.redeem_animation(card, cfg) - Plays the voucher redeem animation, with some customization options.
  • Spectrallib.iter.blinds(blind_keys) - An iterator, used in a for-loop: Takes a list of blind keys and iterates through each of them as Blinds.
  • Spectrallib.iter.areacards(areas) - An iterator, used in a for-loop: Takes a list of cards, a card area, a list of list of cards, or a list of card areas, and iterates through each of their cards.
  • Spectrallib.calculate_starting_asc_power(hand_name, hand_cards, hand_scoring_cards) -> number - 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 - 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.
  • G.UIDEF.bought_decks() -> UINode - This function was missing, causing crashes when viewing the redeemed decks tab, so I nabbed it from Entropy and refactored it
  • ...and probably a few other new functions that I failed to keep track of hhgfhhhh
• ...and probably a few other changes that I also failed to keep track of fhbdnhbkjdfgsdsfk im tired yall