### Usage Example

Source: https://github.com/steamodded/wiki/blob/master/[OUTDATED]-Add-or-Replace-a-Sprite.md

Example demonstrating how to create and register sprite instances using the MOD CORE API SPRITE.

```APIDOC
## Usage Example

```lua
-- Using the "NegateTexturePack" mod as an example

function SMODS.INIT.NegateTexturePack()
    sendDebugMessage("Launching Negate Texture Pack!")

    local negate_mod = SMODS.findModByID("NegateTexturePack")
    local sprite_jkr = SMODS.Sprite:new("Joker", negate_mod.path, "Jokers-negate.png", 71, 95, "asset_atli")
    local sprite_boost = SMODS.Sprite:new("Booster", negate_mod.path, "boosters-negate.png", 71, 95, "asset_atli")
    local sprite_blind = SMODS.Sprite:new("blind_chips", negate_mod.path, "BlindChips-negate.png", 34, 34, "animation_atli", 21)

    sprite_jkr:register()
    sprite_boost:register()
    sprite_blind:register()
end
```
```

--------------------------------

### Starting Shop Context

Source: https://github.com/steamodded/wiki/blob/master/Calculate-Functions.md

This context is used at the beginning of the shop.

```lua
if context.starting_shop then
```

--------------------------------

### Customize Initial Deck in Lua

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/1501a.md

Customize the starting deck in custom Back objects using `SMODS.Back.initial_deck`. Specify Suits and Ranks to include or exclude. The first example blacklists Clubs and Spades, ranks Ace through 10.

```lua
-- This example will create a deck of Clubs and Spades, with ranks Ace through 10
initial_deck = { 
	exclude = true, -- OPTIONAL: turns the lists into blacklists, rather than whitelists
	Suits = {'Diamonds', 'Hearts'}, -- A list of suits to include/exclude
	Ranks = {'King', 'Queen', 'Jack'}, -- A list of ranks to include/exclude
},

-- This example will create a deck of Diamonds and Hearts, with only face cards
initial_deck = { 
	Suits = {'Diamonds', 'Hearts'},
	Ranks = {'King', 'Queen', 'Jack'},
}
```

--------------------------------

### Sticker Sets Configuration Example

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Sticker.md

Defines the pools a sticker is allowed to be applied on. Use this to control where a sticker can appear.

```lua
{
	Joker = true
}
```

--------------------------------

### Example Localization Entry for Card Extra Chips

Source: https://github.com/steamodded/wiki/blob/master/Perma-bonuses.md

An example of how to define a localization entry for `card_extra_chips` under `descriptions.Other`. This specifies the text to be displayed for the bonus.

```lua
            card_extra_chips={
                text={
                    "{C:chips}#1#{} extra chips",
                },
            },
```

--------------------------------

### apply(self, back)

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Back.md

Applies modifiers at the start of a run. To modify the starting deck, events must be used.

```APIDOC
## apply(self, back)

### Description
Apply modifiers at the start of a run. If you want to modify the starting deck, you must use events to do so.

### Parameters
- **back** (any) - The back object.
```

--------------------------------

### apply

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Challenge.md

Applies modifiers at the start of a run.

```APIDOC
## apply(self)

### Description
Applies modifiers at the start of a game run. This method is typically invoked automatically when a new run begins.

### Method Signature
`apply(self)`
```

--------------------------------

### JimboQuip Example with Conditional Text and Effects

Source: https://github.com/steamodded/wiki/blob/master/SMODS.JimboQuip.md

Demonstrates creating a JimboQuip with specific card display, custom particle colors, and conditional text keys based on win/loss state. It also sets a higher weight for this quip.

```lua
SMODS.JimboQuip({
    key = 'black_cat_1',
    extra = {
        center = 'j_ortalab_black_cat',
        particle_colours = {
            G.ARGS.LOC_COLOURS.Ortalab,
            darken(G.ARGS.LOC_COLOURS.Ortalab, 0.5),
            lighten(G.ARGS.LOC_COLOURS.Ortalab, 0.5)
        }
    },
    filter = function(self, type) 
        if next(SMODS.find_card('j_ortalab_black_cat')) then
            if type == 'win' then
                self.extra.text_key = self.key..'_win'
                return true, { weight = 10 }
            elseif type == 'loss' then
                self.extra.text_key = self.key..'_loss'
                return true, { weight = 10 }
            end
        end
    end
})
```

--------------------------------

### Register Deck with SMODS.Back

Source: https://context7.com/steamodded/wiki/llms.txt

Use SMODS.Back to register a new deck. The 'apply' hook runs at game start, and 'calculate' integrates into the scoring pipeline.

```lua
SMODS.Back {
    key = 'glass_deck',
    loc_txt = {
        name = 'Glass Deck',
        text = { 'Start with {C:attention}5{} Glass Cards', 'All cards have', '{C:mult}+#1#{} Mult when scored' },
    },
    config = { extra = { bonus_mult = 2 } },
    atlas = 'my_backs',
    pos = { x = 0, y = 0 },
    initial_deck = {
        suits = { 'Hearts', 'Spades' },
        ranks = { 'Ace', 'King', 'Queen', 'Jack', '10' },
    },

    apply = function(self, back)
        G.E_MANAGER:add_event(Event({
            func = function()
                for i = 1, 5 do
                    local card = SMODS.add_card({ set = 'Enhanced', enhancement = 'm_glass' })
                end
                return true
            end,
        }))
    end,

    calculate = function(self, back, context)
        if context.cardarea == G.play and context.main_scoring and context.individual then
            return { mult = back.config.extra.bonus_mult }
        end
    end,

    loc_vars = function(self, info_queue, back)
        return { vars = { self.config.extra.bonus_mult } }
    end,
}
```

--------------------------------

### Create and Register a New Deck

Source: https://github.com/steamodded/wiki/blob/master/[OUTDATED]-Create-a-Deck.md

Instantiates a new deck object with specified attributes, registers it, and prepares it for game integration. Ensure the slug is unique and does not start with 'b_'.

```lua
local loc_def = {
	["name"]="MyDeck",
	["text"]={
		[1]="My Deck !",
	},
}

local newDeck = SMODS.Deck:new("MyDeck", "my_deck_slug", {my_deck_effect = value}, loc_def)
newDeck:register()
```

--------------------------------

### SMODS.Enhancement: Set Badges Example

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Enhancement.md

Demonstrates how to add custom badges to a card using the 'create_badge' function. Avoid overwriting existing elements to prevent UI issues.

```lua
{
    set_badges = function(self, card, badges)
        badges[#badges+1] = create_badge(localize('k_your_string'), G.C.RED, G.C.BLACK, 1.2 )
    end,
}
```

--------------------------------

### Create Standard Cards in Booster Pack

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Booster.md

Implement the `create_card` function to define how standard cards are generated within a booster pack. This example shows manual creation using `SMODS.create_card`.

```lua
create_card = function(self, card)
    local newCard = SMODS.create_card({set = "Playing Card", area = G.pack_cards, skip_materialize = true})
    return newCard
end,
```

--------------------------------

### Defining a Poker Hand Example

Source: https://github.com/steamodded/wiki/blob/master/SMODS.PokerHand.md

Illustrates the structure for defining a poker hand, including scoring cards and optional attributes like edition and enhancement. Use this to configure custom poker hands.

```lua
{
    { 'S_K', false }, -- King of Spades, does not score
    { 'S_9', true }, -- 9 of Spades, scores
    { 'D_9', true, edition = 'e_negative', enhancement = 'm_lucky' }, -- Negative Lucky 9 of Diamonds, scores
    { 'H_6', false }, -- 6 of Hearts, does not score
    { 'D_3', false, seal = 'Red' } -- Red Seal 3 of Diamonds, does not score
}
```

--------------------------------

### Sticker apply Method Example

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Sticker.md

Handles applying and removing the sticker. By default, sets `card.ability[self.key]` to `config` or `val`. It is recommended to not redefine this function, but if necessary, call the default SMODS.Sticker.apply to retain default functionality.

```lua
function apply(self, card, val)
    -- ... custom logic ...
    return SMODS.Sticker.apply(self, card, val)
end
```

--------------------------------

### Complex UI Layout with Nested Nodes

Source: https://github.com/steamodded/wiki/blob/master/UI-Guide.md

Demonstrates building a complex UI structure using nested Row and Column nodes. This example showcases how to arrange elements vertically and horizontally, with specific configurations for size, alignment, and color.

```lua
{
   n = G.UIT.ROOT,
   config = {r = 0.1, minw = 8, minh = 6, align = "tm", padding = 0.2, colour = G.C.BLACK},
   nodes = {
      {
         n = G.UIT.C,
         config = {minw=4, minh=4, colour = G.C.MONEY, padding = 0.15},
         nodes = {
            {
               n = G.UIT.R,
               config = {minw=2, minh=2, colour = G.C.RED, padding = 0.15},
               nodes = {
                  {n = G.UIT.C, config = {minw=1, minh=1, colour = G.C.BLUE, padding = 0.15}},
                  {n = G.UIT.C, config = {minw=1, minh=1, colour = G.C.BLUE, padding = 0.15}}
               }
            },
            
            {
               n = G.UIT.R,
               config = {minw=2, minh=1, colour = G.C.RED, padding = 0.15},
               nodes = {
                  {n = G.UIT.C, config = {minw=1, minh=1, colour = G.C.BLUE, padding = 0.15}},
                  {n = G.UIT.C, config = {minw=1, minh=1, colour = G.C.BLUE, padding = 0.15}}
               }
            }
         }
      }
   }
}
```

--------------------------------

### Add Quantum Enhancements

Source: https://github.com/steamodded/wiki/blob/master/Calculate-Functions.md

Return a table with enhancement keys and true to apply quantum enhancements to cards. For example, `m_wild = true` makes cards function as wild cards.

```lua
return {
	m_wild = true -- make cards function as wild cards
}
```

--------------------------------

### Scoring Calculation with Additional Parameters

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0827.md

Specify custom scoring parameters used by a Scoring Calculation in the 'parameters' table to optimize calculations. This example includes 'chips', 'mult', and a custom parameter 'modprefix_example_parameter'.

```lua
parameters = {'chips', 'mult', 'modprefix_example_parameter'}
```

--------------------------------

### Create Foil Jokers in Booster Pack

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Booster.md

Implement the `create_card` function to define how special cards, like foil jokers, are generated. This example returns a table directly to `SMODS.create_card` with specific properties.

```lua
create_card = function(self, card)
    return {set = "Joker", area = G.pack_cards, skip_materialize = true, soulable = true, key_append = "unique_string_for_rng", edition = "e_foil"}
end,
```

--------------------------------

### Create Custom CardArea with Mod Object

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/1221a.md

Implement the `custom_card_areas` function on your Mod Object to create a new `CardArea` at the correct point in the run start sequence. This example shows creating a new area below the Jokers area.

```lua
SMODS.current_mod.custom_card_areas = function(game)
	game.my_area = CardArea(
		game.jokers.T.x, game.jokers.T.y + 3,
		game.jokers.T.w, game.jokers.T.h / 2,
		{ card_limit = 1, type = 'joker', highlight_limit = 1 }
	)
end
```

--------------------------------

### Creating and Using a UIBox

Source: https://github.com/steamodded/wiki/blob/master/UI-Guide.md

Demonstrates the creation of a UIBox, which is essential for interactive UIs. A UIBox is instantiated with a definition function and configuration, then placed within an Object node.

```lua
-- A simple UIBox being created:
local my_menu = UIBox({
   definition = my_menu_function(...),
   config = {type = "cm", ...}
})

-- A UIBox must be placed in an Object node!
local my_menu_node = {n=G.UIT.O, config={object = my_menu}}
```

--------------------------------

### Create and Use Custom Event Queue

Source: https://github.com/steamodded/wiki/blob/master/Guide-‐-Event-Manager.md

Demonstrates creating a custom event queue and adding events to it. Events in custom queues may not have a guaranteed order relative to each other.

```lua
G.E_MANAGER.queues.my_cool_queue = {}
-- Later, with empty queues:
G.E_MANAGER:add_event(Event {
    trigger = "after",
    delay = 10,
    func = function()
        print("These events should fire on the same frame")
        return true
    end
})
G.E_MANAGER:add_event(Event {
    trigger = "after",
    delay = 10,
    func = function()
        print("These events don't have a guaranteed order")
        return true
    end
}, "my_cool_queue")
```

--------------------------------

### Blueprint Effect Example

Source: https://github.com/steamodded/wiki/blob/master/Calculate-Functions.md

Example of reimplementing the Brainstorm ability using SMODS.blueprint_effect to copy another joker's ability.

```lua
calculate = function(self, card, context)
	-- Reimplementation of Brainstorm
	local other_joker = G.jokers.cards[1]
	local other_joker_ret = SMODS.blueprint_effect(card, other_joker, context)
	if other_joker_ret then
		return other_joker_ret
	end
end
```

--------------------------------

### Example: Joker Chance Roll Failure Message

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0711a.md

Example of how to return a message when a chance roll fails using the pseudorandom_result context.

```lua
if context.pseudorandom_result and not context.result then
	return {
		message = 'Chance failed!'
	}
end
```

--------------------------------

### Booster Initialization

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Booster.md

Initializes a new booster pack with required and optional parameters. The 'key' and either 'loc_txt' or a localization entry are mandatory. Optional parameters control appearance, collection behavior, and shop weighting.

```APIDOC
## Booster Initialization

### Description
Initializes a new booster pack.

### Parameters
#### Required Parameters
- **key** (string) - Unique identifier for the booster.
- **loc_txt** (string or Localization Entry) - Text to display for the booster, or a reference to a localization entry.

#### Optional Parameters
- **atlas** (string) - Texture atlas for the booster's appearance. Defaults to 'Booster'.
- **pos** (table) - Position of the booster's texture. Defaults to { x = 0, y = 0 }.
- **soul_pos** (table) - Position for the soul texture.
- **soul_atlas** (string) - Texture atlas for the soul.
- **config** (table) - Configuration for the pack, e.g., `{ extra = 3, choose = 1 }` where `extra` is the number of cards and `choose` is the number of choices. Defaults to `{ extra = 3, choose = 1 }`.
- **discovered** (boolean) - Whether the booster is discovered. Defaults to false.
- **no_collection** (boolean) - If true, the booster will not be added to the collection.
- **prefix_config** (any) - Configuration prefix.
- **dependencies** (any) - Dependencies for the booster.
- **display_size** (any) - Size for display.
- **pixel_size** (any) - Pixel size.
- **badge_colour** (any) - Color of the badge.
- **badge_text_colour** (any) - Color of the badge text.
- **pools** (table) - List of keys to ObjectTypes this center should be injected into. Example: `{["Foo"] = true, ["Bar"] = true}`.
- **group_key** (string) - Key to the group name of this booster.
- **cost** (number) - Cost of the booster in the shop. Defaults to 4.
- **weight** (number) - Frequency the pack appears in the shop. Defaults to 1.
- **draw_hand** (boolean) - If true, draw playing cards to hand when this pack is opened. Defaults to false.
- **kind** (string) - Used for grouping packs together.
- **select_card** (string or table or function) - Controls where cards from the pack are saved. Can be a destination area string, a table mapping Sets to areas, or a function `select_card(self, card, pack) -> string?`.
- **disable_shine** (boolean) - Disables the default 'shine' shader. (Added in 1531zeebee)
```

--------------------------------

### SMODS.PokerHandPart Initialization

Source: https://github.com/steamodded/wiki/blob/master/SMODS.PokerHand.md

Demonstrates the basic structure for initializing a PokerHandPart, which is used for building composite hands. It requires a unique key and a function to evaluate hand parts.

```lua
key: "my_hand_part",
func(hand) -> table: -- This expects the same return value format as evaluate on poker hands.
```

--------------------------------

### Get Clean Pool of Items

Source: https://github.com/steamodded/wiki/blob/master/Utility.md

A wrapper for get_current_pool that filters out unavailable items, returning only valid keys. Useful for ensuring you only get usable item keys.

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

--------------------------------

### Taking Ownership of Existing Objects

Source: https://github.com/steamodded/wiki/blob/master/[OUTDATED]-Creating-new-game-objects.md

How to take ownership of vanilla game objects to modify them.

```APIDOC
## Taking Ownership of Existing Objects

To use API functions with a vanilla Joker, Consumable, Voucher or Blind, you must first take ownership of it, providing its slug to the `take_ownership` function:

```lua
SMODS.Joker:take_ownership('jolly_joker'):register()
SMODS.Tarot:take_ownership('fool'):register()
-- and so on, you get the point
```

This only works for vanilla objects that have not been registered by a different mod. After doing this, you can use the object as if it were created by your mod through the API. Note that your mod badge will also be displayed on any vanilla objects you take ownership of.
```

--------------------------------

### Get Random Rank with Pool Support

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Rank-and-SMODS.Suit.md

Use `pseudorandom_element` with `SMODS.Ranks` to get a random rank that respects `in_pool` rules. Provide a unique seed for reproducibility.

```lua
local rank = pseudorandom_element(SMODS.Ranks, pseudoseed('myrank'))
```

--------------------------------

### Simple loc_txt Table with Label

Source: https://github.com/steamodded/wiki/blob/master/Localization.md

A straightforward approach using a single table for label, name, and multi-line text.

```lua
{
    -- The simplest option: use a single table
    label = 'Label',
    name = 'Name',
    text = { 'A moderately long', 'description of', 'your effect.' },
}
```

--------------------------------

### disable

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Blind.md

Reverting effects when this Blind gets disabled.

```APIDOC
## disable

### Description
Reverts effects when this Blind gets disabled.

### Method
(Implicitly called by the game)

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

--------------------------------

### Create Custom Badge with create_badge

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Consumable.md

Demonstrates how to create a custom badge using the `create_badge` function. Specify the text, background color, text color, and scaling for the badge.

```lua
create_badge(localize('k_your_string'), G.C.RED, G.C.BLACK, 1.2 )
```

--------------------------------

### Simple loc_txt Table

Source: https://github.com/steamodded/wiki/blob/master/Localization.md

Use this for a basic name and text description for a single language.

```lua
{ name = 'Name', text = { 'This is example text' } }
```

--------------------------------

### create_UIBox

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Booster.md

Returns the booster's UIBox.

```APIDOC
## create_UIBox(self) -> table

### Description
Returns the booster's UIBox.
```

--------------------------------

### Get Optional Features

Source: https://github.com/steamodded/wiki/blob/master/Internal-Documentation.md

Populates the `SMODS.optional_features` table with all enabled optional features from injected mods.

```lua
SMODS.get_optional_features()
```

--------------------------------

### Setting Blind Context

Source: https://github.com/steamodded/wiki/blob/master/Calculate-Functions.md

This context is used for effects when the blind is started. It provides a reference to the selected blind.

```lua
if context.setting_blind then
```

```lua
context.setting_blind -- boolean value to flag this context, always TRUE
context.blind -- a reference to the selected blind
```

--------------------------------

### SMODS.Back Initialization

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Back.md

Parameters required and optional for initializing SMODS.Back. Required parameters include 'key' and either 'loc_txt' or a localization entry. Optional parameters cover atlas, position, configuration, unlock status, and initial deck customization.

```APIDOC
## SMODS.Back Initialization

### Required Parameters
- **key** (string) - Unique identifier for the back.
- **loc_txt** (string) or localization entry - Text for localization.

### Optional Parameters
- **atlas** (string) - Defaults to 'centers'. Specifies the atlas to use. [(reference)](https://github.com/Steamodded/smods.wiki/SMODS.Atlas#applying-textures-to-cards)
- **pos** (table) - Defaults to `{ x = 0, y = 0 }`. Specifies the position.
- **config** (table) - Defaults to `{}`. Configuration values saved under `G.GAME.selected_back.effect.config`.
- **unlocked** (boolean) - Defaults to `true`. Whether the back is unlocked.
- **discovered** (boolean) - Defaults to `false`. Whether the back is discovered.
- **no_collection** (boolean) - If true, the back is not added to the collection.
- **prefix_config** (any) - Prefix configuration.
- **dependencies** (table) - Table of dependencies.
- **display_size** (table) - Size for display.
- **pixel_size** (table) - Size in pixels.
- **initial_deck** (table) - *(Added in 1501a)* Customizes the starting deck.
    - **ranks** (list) - List of ranks to include/exclude.
    - **suits** (list) - List of suits to include/exclude.
    - **exclude** (boolean) - Defaults to `false`. If true, ranks/suits are treated as blacklists.
```

--------------------------------

### mod.custom_card_areas

Source: https://github.com/steamodded/wiki/blob/master/The-Mod-Object.md

Creates custom CardAreas at the correct point in the run start sequence, ensuring proper loading and integration.

```APIDOC
## mod.custom_card_areas(game)

### Description
*(Added in 1221a)*
This function enables the creation of custom `CardArea` instances. It is designed to be called at the appropriate point during the run start sequence, guaranteeing that all necessary loading processes are handled correctly before the area is utilized.

### Parameters
- `game`: The game object, providing access to game state and elements.

### Function Signature
`SMODS.current_mod.custom_card_areas = function(game)
	-- ... implementation ...
end`

### Example Usage
```lua
SMODS.current_mod.custom_card_areas = function(game)
	game.my_area = CardArea(
		game.jokers.T.x, game.jokers.T.y + 3,
		game.jokers.T.w, game.jokers.T.h / 2,
		{ card_limit = 1, type = 'joker', highlight_limit = 1 }
	)
end
```
```

--------------------------------

### Voucher Creation Parameters

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Voucher.md

Parameters required and optional for initializing a new voucher. This includes essential keys like 'key' and 'loc_txt', and optional parameters for visual and functional customization.

```APIDOC
## Voucher Creation

### Description
Defines the parameters for creating a voucher instance.

### Required Parameters
- **key** (string): The unique identifier for the voucher.
- **loc_txt** (string or Localization Entry): Text to display for the voucher, or a reference to a localization entry.

### Optional Parameters
- **atlas** (string, default: 'Voucher'): The texture atlas to use for the voucher's appearance.
- **pos** (table, default: { x = 0, y = 0 }): The position of the voucher's texture.
- **soul_pos** (table): The position for the soul texture.
- **soul_atlas** (string): The texture atlas for the soul.
- **config** (table, default: {}): Configuration options for the voucher.
- **unlocked** (boolean, default: true): Whether the voucher is initially unlocked.
- **discovered** (boolean, default: false): Whether the voucher is initially discovered.
- **no_collection** (boolean): If true, the voucher will not be added to the collection.
- **prefix_config** (table): Configuration specific to the voucher's prefix.
- **dependencies** (table): List of dependencies for this voucher.
- **display_size** (number): The display size of the voucher.
- **pixel_size** (number): The pixel size of the voucher.
- **badge_colour** (Color): The color of the badge.
- **badge_text_colour** (Color): The color of the badge text.
- **pools** (table): A list of keys to ObjectTypes this center should be injected into. Expects a table like `{"Foo" = true, "Bar" = true}`.
- **cost** (number, default: 10): The cost of the voucher.
- **requires** (list of strings): A list of full keys of vouchers that are required for this voucher.
- **disable_shine** (boolean): Disables the default 'shine' shader. (Added in 1531zeebee)
```

--------------------------------

### mod.reset_game_globals

Source: https://github.com/steamodded/wiki/blob/master/The-Mod-Object.md

Resets global game values at the start of each round, mimicking the behavior of certain vanilla game elements.

```APIDOC
## mod.reset_game_globals(run_start)

### Description
This function is used to set up global game values that should be reset at the beginning of each round. It is analogous to how certain vanilla game elements like Castle, The Idol, Ancient Joker, and Mail-In Rebate function.

### Parameters
- `run_start` (boolean): Indicates whether the function is being called at the very start of a run.

### Function Signature
`mod.reset_game_globals(run_start)`
```

--------------------------------

### Getting Rarity Weight

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Rarity.md

Returns the weight of a rarity. Use this method for finer control over the rarity's weight.

```lua
get_weight(self, weight, object_type) -> number
    - Returns weight. Use for finer control over the rarity's weight.
```

--------------------------------

### Weight System

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Edition.md

Explanation of the weight system and how it affects spawn chances.

```APIDOC
## Weight System

### Default Edition Weights
- Negative: 3
- Polychrome: 3
- Holographic: 14
- Foil: 20

The base chance for an edition to appear in the shop is 4%. Custom editions with a higher weight will reduce the spawn chance of other editions proportionally.

### Voucher Adjustments
- Hone Voucher: Doubles the weights of base editions.
- Glow Up Voucher: Quadruples the weights of base editions.

Custom editions do not automatically benefit from these voucher effects. To include custom editions in voucher functionality, implement the `get_weight` method as follows:

```lua
get_weight = function(self)
	return G.GAME.edition_rate * self.weight
end
```
```

--------------------------------

### Define Button Click Function

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/1501a.md

Define the function that will be called when the text button is clicked. This example prints a message to the console.

```lua
function G.FUNCS.example_button()
    print('You clicked me')
end
```

--------------------------------

### Voucher Sprite Manipulation

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Voucher.md

Advanced sprite manipulation for when a card is created or loaded. This function is used for custom visual setups.

```lua
set_sprites = function(self, card, front)
	-- Custom sprite logic here
end
```

--------------------------------

### Create Vouchers

Source: https://github.com/steamodded/wiki/blob/master/[OUTDATED]-Creating-new-game-objects.md

Instantiate new Vouchers using the SMODS.Voucher:new() constructor. This function takes parameters for name, slug, configuration, position, localization text, cost, and unlock requirements.

```lua
-- SMODS.Voucher:new(name, slug, config, pos, loc_txt, cost, unlocked, discovered, available, requires, atlas)
local v_example = SMODS.Voucher:new('Example', 'example', { extra = 2 }, { x = 0, y = 0 }, {
    name = 'Example',
    text = { '{C:red}+#1#{} discards' },
}, 10, true, false, true, {'v_recyclomancy'}, 'my_mod_voucher')
v_example:register()
```

--------------------------------

### Get Current Music Track

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Sound.md

Retrieve the key of the music track that should be played, based on the `select_music_track` function's return values.

```lua
SMODS.Sound:get_current_music()
```

--------------------------------

### keep_on_use(self, card)

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Consumable.md

Allows a used card to stay where it is or be moved to the consumables area from a booster pack instead of getting destroyed.

```APIDOC
## keep_on_use(self, card)

### Description
Allows a used card to stay where it is or be moved to the consumables area from a booster pack instead of getting destroyed.

### Parameters
- **card**: The consumable card.

### Returns
- **bool**: True to keep the card, false to destroy it.
```

--------------------------------

### Create a Full-Screen Shader with SMODS.ScreenShader

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/1501a.md

Initialize a SMODS.ScreenShader to apply custom visual effects to the entire game screen. Define a key, the shader file path, and functions to control when the shader applies and to send variables to it.

```lua
SMODS.ScreenShader({
	key = 'shader_example',
	path = 'shader_example.fs',
	should_apply = function()
		-- use this function to return true when your shader should be applied
	end,
	send_vars = function(self)
		return {
			-- use this table to return any values that your shader needs to access from the game
		}
	end,
})
```

--------------------------------

### Get Clean Card Pool in Lua

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/1501a.md

This function, `SMODS.get_clean_pool`, is a wrapper for `get_current_pool` that filters out unavailable values, returning only valid keys.

```lua
function SMODS.get_clean_pool(_type, _rarity, _legendary, _append)

```

--------------------------------

### Rendering CanvasSprites Manually

Source: https://github.com/steamodded/wiki/blob/master/SMODS.CanvasSprite.md

Provides a basic guide on how to manually render CanvasSprites using an SMODS.DrawStep and Love2D's graphics functions.

```APIDOC
## Rendering CanvasSprites Yourself

### Description
This section outlines the basic steps for manually rendering CanvasSprites using an `SMODS.DrawStep` and Love2D's graphics functions. Refer to [Love2D's graphics documentation](https://love2d.org/wiki/love.graphics) for detailed graphics features.

### Steps
1.  **Create an `SMODS.DrawStep`**: Define a DrawStep with a `func`.
2.  **Check for CanvasSprite**: Inside the `func`, verify if the card has the CanvasSprite (e.g., `if card.canvas_text`).
3.  **Render the Canvas**: Use the following structure within the `func` (assuming the CanvasSprite is at `card.canvassprite`):
    ```lua
    love.graphics.push()
    love.graphics.origin()
    card.canvassprite.canvas:renderTo(love.graphics.clear, 0, 0, 0, 0)
    -- Your custom rendering code here
    love.graphics.pop()
    ```

### Explanation
- `love.graphics.push()` and `love.graphics.pop()`: Safely manage the graphics state.
- `love.graphics.origin()`: Resets the drawing origin to the top-left of the canvas.
- `card.canvassprite.canvas:renderTo(love.graphics.clear, 0, 0, 0, 0)`: Renders the canvas content and clears it to full transparency each frame.
```

--------------------------------

### Create a Quip Object with Customization

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0827.md

Use SMODS.JimboQuip to create a quip object with specific keys, extra configurations like center and particle colors, and a filter function to determine when the quip should appear.

```lua
SMODS.JimboQuip({
	key = 'black_cat_1',
	extra = {
		center = 'j_ortalab_black_cat',
		particle_colours = {
			G.ARGS.LOC_COLOURS.Ortalab,
			darken(G.ARGS.LOC_COLOURS.Ortalab, 0.5),
			lighten(G.ARGS.LOC_COLOURS.Ortalab, 0.5)
		}
	},
	filter = function(self, type)
		if next(SMODS.find_card('j_ortalab_black_cat')) then
			if type == 'win' then
				self.extra.text_key = self.key..'_win'
				return true, { weight = 10 }
			elseif type == 'loss' then
				self.extra.text_key = self.key..'_loss'
				return true, { weight = 10 }
			end
		end
end
})
```

--------------------------------

### Create Planets, Tarots, and Spectrals

Source: https://github.com/steamodded/wiki/blob/master/[OUTDATED]-Creating-new-game-objects.md

Use the respective :new() functions to create instances of Planets, Tarots, and Spectrals. Ensure all required parameters are provided, and call :register() to make them available in the game.

```lua
-- SMODS.Planet:new(name, slug, config, pos, loc_txt, cost, cost_mult, effect, freq, consumeable, discovered, atlas)
local c_example_planet = SMODS.Planet:new('Example Planet', 'example_planet', { hand_type = 'Custom Hand Type' }, {x = 0, y = 0 }, nil, 3, 1, nil, nil, nil, nil, 'my_mod_tarot')
-- SMODS.Tarot:new(name, slug, config, pos, loc_txt, cost, cost_mult, effect, consumeable, discovered, atlas)
local c_example_tarot = SMODS.Tarot:new('Example Tarot', 'example_tarot', {}, { x = 1, y = 0 }, {
   name = 'Example Tarot',
   text = { 'Does nothing?' }
}, 3, 1, nil, nil, nil, 'my_mod_tarot')
-- SMODS.Spectral:new(name, slug, config, pos, loc_txt, cost, consumeable, discovered, atlas)
local c_example_spectral = SMODS.Spectral:new('Example Spectral', 'example_spectral', { mult = 4 }, { x = 2, y = 0 }, {
    name = 'Example Spectral',
    text = { 'Does nothing?', '{C:inactive}Or does it?' }
}, 4, nil, nil, 'my_mod_tarot')
c_example_planet:register()
c_example_tarot:register()
c_example_spectral:register()
```

--------------------------------

### Get Size of Pool

Source: https://github.com/steamodded/wiki/blob/master/Utility.md

Calculates the number of valid keys within a pool obtained from get_current_pool. Useful for determining the number of available items.

```lua
SMODS.size_of_pool(pool)
```

--------------------------------

### Define Edition Configurable Parameters

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Edition.md

This table defines base values for the 'config' parameter, which are automatically applied and scored. Ensure these values are appropriate for the edition's intended gameplay impact.

```lua
{
	chips = 10,
	mult = 10,
	x_mult = 2,
	p_dollars = 3,
	card_limit = 2,
}
```

--------------------------------

### Track Score with SMODS.calculate_round_score

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0827.md

Use `SMODS.calculate_round_score()` to get the equivalent value of `hand_chips * mult` after the scoring calculation has been changed. This ensures accurate score tracking.

```lua
SMODS.calculate_round_score()
```

--------------------------------

### SMODS.JimboQuip Constructor

Source: https://github.com/steamodded/wiki/blob/master/SMODS.JimboQuip.md

Defines a new JimboQuip with required and optional parameters.

```APIDOC
## SMODS.JimboQuip

JimboQuips allow you to create new pop ups at the end of a run.

### Parameters

#### Required parameters:
- **key** (string): A unique identifier for the quip.
- **loc_txt** or localization entry (string): The text content of the quip, or a key for localization.
    - For use with localization file, the text should be set as `G.localization.misc.quips[key:lower()]`.
    - `loc_txt` should only contain the text, without key-indexing.

#### Optional parameters:
- **prefix_config** (table): Configuration for prefixes. (See [Common Parameters](https://github.com/Steamodded/smods/wiki/API-Documentation#common-parameters))
- **dependencies** (table): Dependencies for the quip. (See [Common Parameters](https://github.com/Steamodded/smods/wiki/API-Documentation#common-parameters))
- **type** (string): The type of quip, e.g., 'win' or 'loss'. Can be other strings for modded types.
- **extra** (table or function): A table of parameters to customize the quip, or a function that returns this table.
    - **center** (string): Key of the card to show.
    - **particle_colours** (table): Table of up to 3 colours for particles.
    - **materialize_colours** (table): Table of up to 3 colours for materialize effect.
    - **text_key** (string): Key override for the quip.
    - **times** (number): Number of times to play sounds.
    - **pitch** (number): Pitch of sounds.
    - **sound** (string or table): String or table of sounds to play.
    - **juice** (table): Arguments to pass into `card:juice_up`.
    - **delay** (number): Amount to delay the next loop of sounds.

### Example
```lua
SMODS.JimboQuip({
    key = 'black_cat_1',
    extra = {
        center = 'j_ortalab_black_cat',
        particle_colours = {
            G.ARGS.LOC_COLOURS.Ortalab,
            darken(G.ARGS.LOC_COLOURS.Ortalab, 0.5),
            lighten(G.ARGS.LOC_COLOURS.Ortalab, 0.5)
        }
    },
    filter = function(self, type)
        if next(SMODS.find_card('j_ortalab_black_cat')) then
            if type == 'win' then
                self.extra.text_key = self.key..'_win'
                return true, { weight = 10 }
            elseif type == 'loss' then
                self.extra.text_key = self.key..'_loss'
                return true, { weight = 10 }
            end
        end
    end
})
```
```

--------------------------------

### Dynamic Background Color with Variables

Source: https://github.com/steamodded/wiki/blob/master/Text-Styling.md

Combine background color modifiers with loc_vars to dynamically set the background color. This example shows a multiplier based on a variable.

```pas
{X:mult,C:white} X#1# {}     
```

```lua
vars = {
  card.ability.extra.xmult -- 0.5
}
```

--------------------------------

### Combine Text Color and Variables

Source: https://github.com/steamodded/wiki/blob/master/Text-Styling.md

Combine text color modifiers with loc_vars to dynamically set text. This example shows how to display a chance based on variables.

```pas
{C:green}#1# іn #2#{} chance     
```

```lua
vars = {
  G.GAME.probabilities.normal, -- 1
  card.ability.extra.odds      -- 6
}
```

--------------------------------

### Defining ObjectType Cards

Source: https://github.com/steamodded/wiki/blob/master/SMODS.ObjectType.md

When defining an ObjectType, 'cards' expects a list of keys to centers to auto-inject into this ObjectType. This example shows the expected format for the 'cards' parameter.

```lua
{
				["j_foo_joker"] = true,
				["c_bar_tarot"] = true,
			}
```

--------------------------------

### ease_background_colour

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Booster.md

Changes the background color while the booster is opened.

```APIDOC
## ease_background_colour(self)

### Description
Changes the background color whilst this booster is opened.
```

--------------------------------

### Create Custom Card Areas

Source: https://github.com/steamodded/wiki/blob/master/The-Mod-Object.md

Define a custom 'CardArea' that is correctly loaded during the run start sequence. This ensures proper loading of any associated assets or logic.

```lua
SMODS.current_mod.custom_card_areas = function(game)
	game.my_area = CardArea(
		game.jokers.T.x, game.jokers.T.y + 3,
        game.jokers.T.w, game.jokers.T.h / 2,
			{ card_limit = 1, type = 'joker', highlight_limit = 1 }
	)
end
```

--------------------------------

### Increase Mult for Flushes

Source: https://github.com/steamodded/wiki/blob/master/Calculate-Functions.md

This example increases the mult for Flush-type hands and returns a custom message. It checks for Flushes before main scoring and applies the mult during main scoring.

```lua
calculate = function(self, card, context) 
    -- Check if we have played a Flush before we do any scoring and increment the mult
    if context.before and next(context.poker_hands['Flush']) then
        card.ability.extra.mult = card.ability.extra.mult + card.ability.extra.change
        return {
            message = 'Upgraded!',
            colour = G.C.RED
        }    
    end
    -- Add the mult in main scoring context
    if context.joker_main then
        return {
            mult = card.ability.extra.mult
        }
    end
end
```

--------------------------------

### Increase Chips Value

Source: https://github.com/steamodded/wiki/blob/master/Calculate-Functions.md

Access and modify values stored in the object's `config.extra` using `card.ability.extra`. This example increases the chips value by a defined change amount.

```lua
card.ability.extra.chips = card.ability.extra.chips + card.ability.extra.change
```

--------------------------------

### Set Scoring Calculation with SMODS.set_scoring_calculation

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0827.md

Change the scoring calculation method during a game by calling `SMODS.set_scoring_calculation` with the desired modprefix. For example, use `'modprefix_minus'` to switch to a specific calculation.

```lua
SMODS.set_scoring_calculation('modprefix_minus')
```

--------------------------------

### Initial Scoring Step Context Variables

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0711a.md

Lists variables available within the initial_scoring_step context.

```lua
context.cardarea, context.full_hand, context.scoring_hand, context.scoring_name, context.poker_hands,
context.initial_scoring_step -- boolean value to flag this context, always TRUE
```

--------------------------------

### Setting Initial Ability Values and Sprites

Source: https://github.com/steamodded/wiki/blob/master/SMODS.Center/SMODS.Joker.md

Used to set up initial ability values for a card or manipulate sprites in an advanced manner upon card creation.

```lua
set_ability = function(self, card, initial, delay_sprites)
	-- Set initial ability values or manipulate sprites
end
```

--------------------------------

### Defining ObjectType Rarities

Source: https://github.com/steamodded/wiki/blob/master/SMODS.ObjectType.md

The 'rarities' parameter for ObjectType allows cards to show up at different rates. This example demonstrates the expected list of tables, each containing a 'key' and a 'rate'.

```lua
{
				key = '',
				rate = 0.5,
			}
```

--------------------------------

### Buying Card from Shop

Source: https://github.com/steamodded/wiki/blob/master/Calculate-Functions.md

This context is used when purchasing a card, including Vouchers, from the shop. Be cautious as the card being bought evaluates twice; use `context.buying_self` to ensure actions are performed only on the specific card being bought.

```lua
if context.buying_card then
```

```lua
context.buying_card -- flag to identify this context, always TRUE
context.card -- the card that was bought
context.buying_self -- true when the evaluated card is the card that is being bought. recommended to use instead of context.buying_card when applicable
```

--------------------------------

### Localization Keys for Tooltips

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0827.md

Add these localization entries to enable dynamic tooltips based on the area. If an entry is missing, it defaults to the standard edition entry.

```lua
'e_modprefix_editionkey' -- When in the joker area or on a joker in the shop
```

```lua
'e_modprefix_editionkey_consumable' -- When in the consumable area or on a consumable in the shop
```

```lua
'e_modprefix_editionkey_playing_card' -- When in the hand or on a playing card in the shop
```

```lua
'e_modprefix_editionkey_generic' -- In any area without a key or other objects in the shop
```

--------------------------------

### Migrate SMODS.INIT Code

Source: https://github.com/steamodded/wiki/blob/master/02.-Migration-guide.md

Code previously inside SMODS.INIT should be moved to the top-level scope.

```lua
SMODS.INIT
-- Move all code inside SMODS.INIT to top-level scope
```

--------------------------------

### Combine Text and Background Color Modifiers

Source: https://github.com/steamodded/wiki/blob/master/Text-Styling.md

Combine multiple modifiers within a single set of curly braces. This example sets text to white and applies a multiplier effect.

```pas
{X:mult,C:white}X0.5{}     
```

--------------------------------

### Define Challenge Apply Function

Source: https://github.com/steamodded/wiki/blob/master/Release Notes/0827.md

Use the `apply` function within challenges to gain more control over the changes made. This example sets the game's stake to Gold Stake.

```lua
apply = function(self)
	G.GAME.stake = 8 -- sets the stake to Gold Stake
end
```

--------------------------------

### Implement Custom Deck Effects

Source: https://github.com/steamodded/wiki/blob/master/[OUTDATED]-Create-a-Deck.md

Extends the 'Back.apply_to_run' function to add custom logic for deck effects, such as applying 'polyglass' to cards. Always call the original function reference to maintain compatibility with other mods.

```lua
-- Using the "AbsoluteDeck" mod as an example


-- Save function ref so we can append some logic to it
local Backapply_to_runRef = Back.apply_to_run
-- Function used to apply new Deck effects
function Back.apply_to_run(arg_56_0)
	Backapply_to_runRef(arg_56_0)

	if arg_56_0.effect.config.polyglass then
		G.E_MANAGER:add_event(Event({
			func = function()
				for iter_57_0 = #G.playing_cards, 1, -1 do
					sendDebugMessage(G.playing_cards[iter_57_0].base.id)

					G.playing_cards[iter_57_0]:set_ability(G.P_CENTERS.m_glass)
					G.playing_cards[iter_57_0]:set_edition({
						polychrome = true
					}, true, true)
				end

				return true
			end
		}))
	end
end
```

--------------------------------

### Basic UI Element Node

Source: https://github.com/steamodded/wiki/blob/master/UI-Guide.md

A fundamental UIElement node demonstrating a simple text display within a column layout. This serves as a basic example of how UI elements are structured.

```lua
-- Example node:
{
   n = G.UIT.C,
   config = {align = "cm", padding = 0.1},
   nodes = {
      {n = G.UIT.T, config = {text = "Hello, world!", colour = G.C.UI.TEXT_LIGHT, scale = 0.5}}
   }
}
```