|
| 1 | +# Internal Documentation |
| 2 | +SMODS has internal functions that are used for loading mods, creating and handling GameObjects, and general backend operations. Mods may be interested in using or modifying these functions. |
| 3 | + |
| 4 | +- [Injection](#injection) |
| 5 | +- [Calculation](#calculation) |
| 6 | +- [Misc.](#misc) |
| 7 | + |
| 8 | +*** |
| 9 | + |
| 10 | +## Injection |
| 11 | +These are functions used during the injection process of mods or GameObjects. |
| 12 | +#### `SMODS.save_d_u(o)` |
| 13 | +Saves the default discovery and unlock states of an object into a separate field for later use before they are overwritten with profile data. |
| 14 | +#### `SMODS.SAVE_UNLOCKS()` |
| 15 | +Modified from base game code. Sets discovery and unlock data according to profile state after injection. |
| 16 | +#### `SMODS.process_loc_text(ref_table, ref_value, loc_txt, key)` |
| 17 | +Saves a localization entry (usually consisting of a name and a description) into the game's dictionary, with the ability to handle a multi-language format. The `loc_txt` table should either have locale indexing at the top layer or none at all. If the table holds multiple entries, `key` can be used to choose a key one layer down. |
| 18 | +- Example: `SMODS.process_loc_text(G.localization.descriptions.Joker, 'my_joker_key', loc_txt)` |
| 19 | +#### `SMODS.handle_loc_file(path)` |
| 20 | +Given a mod's path, reads any present localization files and adds entries to the dictionary. |
| 21 | +#### `SMODS.modify_key(obj, prefix, condition, key)` |
| 22 | +Modifies a string within the object to include provided `prefix`. |
| 23 | +#### `SMODS.add_prefixes(cls, obj, from_take_ownership)` |
| 24 | +Injects prefixes into the object. This includes the `key` of the object and any tables expecting keys of objects (e.x. `applied_stakes`). |
| 25 | +#### `SMODS.insert_pool(pool, center, replace)` |
| 26 | +If `replace` is true or `center` has been taken ownership of, look for an entry in `pool` with the same key and replace it. Otherwise, append `center` to the end of `pool`. |
| 27 | +#### `SMODS.remove_pool(pool, key)` |
| 28 | +Find an entry in pool with this `key` and remove it if found. |
| 29 | +#### `SMODS.create_loc_dump()` |
| 30 | +Dumps localization entries created during injection into a single file, for purposes of converting to a file-based localization system. |
| 31 | +#### `SMODS.create_mod_badges(obj, badges)` |
| 32 | +UI code for adding mod badges to an object. |
| 33 | +#### `SMODS.merge_defaults(t, defaults) -> t?` |
| 34 | +Starting with `t`, insert any key-value pairs from `defaults` that don't already exist in `t` into `t`. Modifies `t` and returns it as the result of the merge. |
| 35 | +- `nil` entries are interpreted as an empty table; `false` inputs count as a table where every possible key maps to `false`. Therefore, `t == nil` is weak and falls back to defaults, while `t == false` explicitly ignores `defaults` in its entirety. Due to this, this function may not always return a table. |
| 36 | +- This is used for controlling when keys should receive prefixes. |
| 37 | +#### `convert_save_data()` |
| 38 | +Adjusts values in save data to make the save compatible with Steamodded's way of storing deck wins by stake key instead of index. |
| 39 | +#### `SMODS.restart_game()` |
| 40 | +Restarts the game. |
| 41 | +#### `SMODS.get_optional_features()` |
| 42 | +Inserts all enabled optional features by injected mods into the `SMODS.optional_features` table. |
| 43 | +#### `SMODS.localize_box(lines, args)` |
| 44 | +Handles localizing description boxes within a localization entry. |
| 45 | + |
| 46 | +## Calculation |
| 47 | +These functions are used for handling calculation events. |
| 48 | +#### `SMODS.calculate_context(context, return_table) -> table?` |
| 49 | +Main function used to calculate effects on cards for the provided `context` over a majority of CardAreas. |
| 50 | +- If `return_table` is provided, the function will not return a table and instead put all the calculation returns into |
| 51 | +- Mods can hook this function to add extra CardAreas. |
| 52 | +#### `SMODS.calculate_card_areas(_type, context, return_table, args) -> table` |
| 53 | +Calculates effects on cards for a specific group of CardAreas based on `_type`. |
| 54 | +#### `SMODS.score_card(card, context)` |
| 55 | +Scores the provided `card`. |
| 56 | +#### `SMODS.calculate_main_scoring(context, scoring_hand)` |
| 57 | +Handles the main scoring hand calculation event. |
| 58 | +- `scoring_hand` - Uses this table of cards if provided, else it looks through `context.cardarea.cards` for if any of them are inside of `context.scoring_hand`. |
| 59 | +#### `SMODS.calculate_end_of_round_effects(context)` |
| 60 | +Handles the end of round calculation event. |
| 61 | +#### `SMODS.calculate_destroying_cards(context, cards_destroyed, scoring_hand)` |
| 62 | +Handles the card destroy calculation event. |
| 63 | +- `scoring_hand` - Uses this table of cards if provided, else it looks through `context.cardarea.cards` for if any of them are inside of `context.scoring_hand`. |
| 64 | +#### `SMODS.calculate_individual_effect(effect, scored_card, key, amount, from_edition)` |
| 65 | +Used to trigger a calculation effect based on provided `key`. |
| 66 | +#### `SMODS.calculate_effect_table_key(effect_table, key, card, ret)` |
| 67 | +Triggers one key of an effect table returned from `eval_card`. |
| 68 | +#### `SMODS.trigger_effects(effects, card)` |
| 69 | +Used to calculate a table of effects generated in `G.FUNCS.evaluate_play`. |
| 70 | +#### `SMODS.get_card_areas(_type, _context) -> table` |
| 71 | +Returns a table of CardAreas based on the provided `_type` and `_context`. Can be hooked or injected into to add your own CardAreas. |
| 72 | +- Possible values of `_type`: |
| 73 | + - `"playing_cards"` - Playing card evaluation. |
| 74 | + - Default CardAreas are `G.hand`, `G.play` (if `_context` is not `"end_of_round"`), `G.deck` (if the "Deck Calculation" feature is enabled), and `G.discard` (if the "Discard Calculation" feature is enabled). |
| 75 | + - `"jokers"` - Joker evaluation. |
| 76 | + - Default CardAreas are `G.jokers`, `G.consumeables`, and `G.vouchers`. |
| 77 | + - `"individual"` - Individual object evaluation. |
| 78 | + - Unlike above, this does not return CardAreas and instead returns tables with an `object` and `scored_card` field. `object` if the object that will have the `calculate` function called on, and `scored_card` is the card/object used for animation. |
| 79 | + - Default objects are the selected Back and the selected Blind. |
| 80 | +- `_context` - Optional string to indicate extra information about the context. |
| 81 | +#### `SMODS.calculate_retriggers(card, context, _ret) -> table` |
| 82 | +Calculates the retriggers on a Joker. Requires the "Joker Retrigger" feature to be enabled. |
| 83 | +#### `SMODS.calculate_repetitions(card, context, reps)` |
| 84 | +Calculates the repetitions on a playing card. |
| 85 | +#### `SMODS.get_enhancements(card, extra_only) -> table<key, true>` |
| 86 | +Returns a table of key-bool pairs, the keys being the enhancements this card counts as having. |
| 87 | +- If the "Quantum Enhancement" feature is not enabled, this function will only return the card's current enhancement. |
| 88 | +- `extra_only` - The returned table will exclude the card's current enhancement. |
| 89 | +#### `SMODS.calculate_quantum_enhancements(card, effects, context)` |
| 90 | +Calculates quantum enhancements. Requires the "Quantum Enhancements" feature to be enabled. |
| 91 | +#### `SMODS.shatters(card) -> bool` |
| 92 | +Returns true if the card should be shattered. |
| 93 | +#### `SMODS.in_scoring(card, scoring_hand) -> bool` |
| 94 | +Returns true if the card is within the scoring hand. |
| 95 | +#### `SMODS.push_to_context_stack(context, func)` |
| 96 | +Pushes `context` into `SMODS.context_stack`. |
| 97 | +#### `SMODS.pop_from_context_stack(context, func)` |
| 98 | +Pops a `context` from `SMODS.context_stack`. |
| 99 | +#### `SMODS.get_previous_context()` |
| 100 | +Returns the second to last context from `SMODS.context_stack` |
| 101 | + |
| 102 | +## Misc. |
| 103 | +These are functions used by SMODS for miscellaneous features. |
| 104 | +#### `SMODS.signed(val) -> string` |
| 105 | +Returned a signed string of `val`, prefixed with "+" if positive. |
| 106 | +#### `SMODS.signed_dollars(val) -> string` |
| 107 | +Returned a signed string of `val` as dollars, prefixed with "$" if positive and "-$" if negative. |
| 108 | +#### `SMODS.multiplicative_stacking(base, perma) -> number` |
| 109 | +Returns the result of multiplying `base` and `perma + 1`. |
| 110 | +#### `SMODS.add_to_pool(prototype_obj, args) -> bool?, table?` |
| 111 | +Helper function to check if an object can be added into a pool, |
| 112 | +- If `prototype_obj.in_pool` is defined, returns the result of `in_pool`, otherwise returns `false`. |
0 commit comments