### Installation Guides

Source: https://github.com/steamodded/smods/wiki/_Sidebar

Guides for installing Steamodded on different operating systems.

```APIDOC
## Installation Guides

### Description
Provides instructions for installing Steamodded on various platforms.

### Platforms
- **Windows**: [Link](https://github.com/Steamodded/smods/wiki/Installing-Steamodded-windows)
- **Linux**: [Link](https://github.com/Steamodded/smods/wiki/Installing-Steamodded-linux)
- **Mac**: [Link](https://github.com/Steamodded/smods/wiki/Installing-Steamodded-mac)
- **Android/iOS**: [Link](https://github.com/Steamodded/smods/wiki/Installing-Steamodded-mobile)
```

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

### Example Usage

Source: https://github.com/steamodded/smods/blob/main/libs/nativefs/README.md

A practical example demonstrating how to use `nativefs.getDirectoryItemsInfo` and `nativefs.getInfo`.

```APIDOC
## Example Usage

### Description
This example demonstrates how to list files in a directory and retrieve detailed information about them using `nativefs.getDirectoryItemsInfo` and `nativefs.getInfo`.

### Code Example

```lua
local nativefs = require("nativefs")

-- Prints all information on files in C:\Windows
local files = nativefs.getDirectoryItemsInfo("C:/Windows")
for i = 1, #files do
  if files[i].type == "file" then
    local info = nativefs.getInfo("C:/Windows/" .. files[i].name)
    print(i .. ": " .. files[i] .. " : Type:" .. info.type .. ", Size:" .. tostring(info.size) .. ", last modified:" .. tostring(info.modtime))
  end
end
```
```

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

### Create Custom Starting Deck with SMODS.Back

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

Define a custom starting deck with unique effects and modified starting hands. This example creates a deck that starts with only red cards and grants bonus mult.

```lua
-- Create a deck that starts with only red cards and bonus mult
SMODS.Back {
  key = 'crimson_deck',
  loc_txt = {
    name = 'Crimson Deck',
    text = {
      'Start with only {C:hearts}Hearts{} and {C:diamonds}Diamonds{}',
      '{C:red}+2{} Mult on every hand'
    }
  },
  atlas = 'my_decks',
  pos = { x = 0, y = 0 },
  config = { extra_mult = 2 },

  -- Only include Hearts and Diamonds in starting deck
  initial_deck = {
    suits = { 'Hearts', 'Diamonds' }
  },

  apply = function(self, back)
    -- Additional setup at run start
    G.GAME.starting_params.extra_mult = (G.GAME.starting_params.extra_mult or 0) + self.config.extra_mult
  end,

  calculate = function(self, back, context)
    if context.joker_main then
      return {
        mult = G.GAME.selected_back.effect.config.extra_mult,
        message = '+2 Mult'
      }
    end
  end
}
```

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

### DeckSkin Crediting Example

Source: https://github.com/steamodded/smods/wiki/SMODS.DeckSkin

An example demonstrating how to use `has_ds_card_ui` and `generate_ds_card_ui` for crediting artists in the deck skin preview.

```APIDOC
## DeckSkin Crediting

Steammodded provides built-in methods to force enable card UI in the Customize Deck menu, allowing artists to be credited for DeckSkins.

### Enabling the UI (`has_ds_card_ui`)
This function is called for each card in the preview. If it returns `true`, the UI is enabled for that card. You can filter enabled UI by checking card rank, palette key, etc.

```lua
has_ds_card_ui = function(card, deckskin, palette)
    if card.base.value == "King" then 
        return true
    end
end
```

### Defining the UI (`generate_ds_card_ui`)
This function defines the contents of the UI for cards where `has_ds_card_ui` returned true. It works similarly to `generate_ui` for Centers.

```lua
generate_ds_card_ui = function(card, deckskin, palette, info_queue, desc_nodes, specific_vars, full_UI_table)
    if card.base.value == "King" then
        localize{type = 'other', key = 'artist', nodes = desc_nodes, vars = {}} 
        localize{type = 'other', key = 'artist_credit', nodes = desc_nodes, vars = { "ARTIST NAME HERE" }}
    end
end
```

![Visual example of the default crediting format used in the above code, seen in Balatro: Cardsauce](https://i.imgur.com/pZ1XIP2.jpg)
```

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

### Check for context.starting_shop

Source: https://github.com/steamodded/smods/wiki/Calculate-Functions

This context is used when starting the shop.

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

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

### Complete JimboQuip Example with Conditional Text

Source: https://github.com/steamodded/smods/wiki/SMODS.JimboQuip

An example demonstrating the creation of a JimboQuip with conditional text keys for win and loss scenarios. It also customizes particle colors and sets a high weight for display frequency.

```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
})
```

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

### Get Poker Hand Info Example

Source: https://github.com/steamodded/smods/wiki/Guide-‐-Joker-Calculation

This example shows how to call `G.FUNCS.get_poker_hand_info` to determine the details of a played hand. It returns the hand name, localized name, all possible poker hands, the specific cards that are scoring, and a customized hand name.

```lua
local hand_name, localized_hand_name, poker_hands, scoring_hand, customised_hand_name = G.FUNCS.get_poker_hand_info(..)
```

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

### Guides

Source: https://github.com/steamodded/smods/wiki/_Sidebar

Various guides for mod development and usage.

```APIDOC
## Guides

### Description
This section contains various guides related to modding with SMODS.

### Topics
- **Your First Mod**: [Link](https://github.com/Steamodded/smods/wiki/Your-First-Mod)
- **Mod Metadata**: [Link](https://github.com/Steamodded/smods/wiki/Mod-Metadata)
- **The Mod Object**: [Link](https://github.com/Steamodded/smods/wiki/The-Mod-Object)
- **Calculate Functions**: [Link](https://github.com/Steamodded/smods/wiki/Calculate-Functions)
- **Perma-bonuses**: [Link](https://github.com/Steamodded/smods/wiki/Perma-bonuses)
- **Object Weights**: [Link](https://github.com/Steamodded/smods/wiki/Weight-System)
- **Logging**: [Link](https://github.com/Steamodded/smods/wiki/Logging)
- **Event Manager**: [Link](https://github.com/Steamodded/smods/wiki/Guide-%E2%80%90-Event-Manager)
- **Localization**: [Link](https://github.com/Steamodded/smods/wiki/Localization)
- **Text Styling**: [Link](https://github.com/Steamodded/smods/wiki/Text-Styling)
- **UI Structure**: [Link](https://github.com/Steamodded/smods/wiki/UI-Guide)
- **Utility Functions**: [Link](https://github.com/Steamodded/smods/wiki/Utility)
- **All About `G`**: [Link](https://github.com/Steamodded/smods/wiki/G)
- **Internal Documentation**: [Link](https://github.com/Steamodded/smods/wiki/Internal-Documentation)
```

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

### Example Sticker Set Configuration

Source: https://github.com/steamodded/smods/wiki/SMODS.Sticker

Defines the pools a sticker is allowed to be applied on. This example shows a sticker allowed on the 'Joker' pool.

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

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

### SMODS.Edition Config Example

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Edition

Base values for config that are supported and will be applied/scored automatically.

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

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

### Apply Modifiers at Run Start

Source: https://github.com/steamodded/smods/wiki/SMODS.Challenge

The `apply` method is intended for applying modifiers at the beginning of a game run. Ensure any necessary setup or state changes are handled here.

```lua
apply(self)
```

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

### Minimal Context Example

Source: https://github.com/steamodded/smods/wiki/Guide-‐-Joker-Calculation

This example demonstrates the structure of a bare-minimum context object used in Balatro's score evaluation. It includes essential information like the card area, the full hand, scoring hand details, and the name of the play.

```lua
local minimal_context = {
   cardarea = G.jokers,
   full_hand = G.play.cards,
   scoring_hand = scoring_hand, -- from G.FUNCS.get_poker_hand_info(..)
   scoring_name = hand_name,    -- from G.FUNCS.get_poker_hand_info(..)
   poker_hands = poker_hands    -- from G.FUNCS.get_poker_hand_info(..)
}
```

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

### Object Node Configuration Example

Source: https://github.com/steamodded/smods/wiki/UI-Guide

Shows how to configure an Object node (G.UIT.O) by specifying the object to render and its role within the UI hierarchy.

```lua
{
  n = G.UIT.O,
  config = {
    object = CardArea,
    role = {role_type = "Major"}
  }
}
```

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

### Pre-existing PokerHandPart Examples

Source: https://github.com/steamodded/smods/wiki/SMODS.PokerHand

Examples of pre-existing parts available in SMODS.PokerHandPart, such as groups of cards by rank, pairs, flushes, straights, and the highest card.

```lua
parts._2, parts._3, parts._4, parts._5
```

```lua
parts._all_pairs
```

```lua
parts._flush
```

```lua
parts._straight
```

```lua
parts._highest
```

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

### SMODS.Edition Pools Example

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Edition

Defines a list of ObjectTypes keys that this center should be injected into. Expects a list of keys.

```lua
{
		["Foo"] = true,
		["Bar"] = true,
	}
```

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

### Basic Node Configuration Example

Source: https://github.com/steamodded/smods/wiki/UI-Guide

Demonstrates basic node configuration including alignment, dimensions, padding, and color. The 'align' property uses two letters for vertical and horizontal positioning.

```lua
{
  align = "tl",
  w = 0.1,
  h = 0.2,
  padding = 0.05,
  r = 0.1,
  colour = HEX("000000FF"),
  outline_colour = G.C.WHITE,
  no_fill = true,
  hover = true,
  shadow = true,
  juice = true
}
```

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

### Info Log Output Format

Source: https://github.com/steamodded/smods/wiki/Logging

Example of how info messages are formatted in the log output.

```log
2024-04-04 22:58:45 :: INFO  :: MyInfoLogger :: This is an info message
```

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

### Playing Sounds

Source: https://github.com/steamodded/smods/wiki/SMODS.Sound

Instructions and examples for playing sounds using the `play_sound` function and within effect tables.

```APIDOC
## Playing Sounds

### `play_sound(key, pitch, volume)`

#### Description
Plays a sound at any time.

#### Parameters
- **key** (string) - The identifier of the sound to play. Must include the mod prefix.
- **pitch** (number, optional) - The pitch shift for the sound.
- **volume** (number, optional) - The volume for the sound.

#### Example
```lua
play_sound('MyMod_MyCoolSound', 0.7, 0.55)
```

### Playing Sounds from Effect Tables

It is possible to play a sound with any message returned from a [calculate function](https://github.com/Steamodded/smods/wiki/calculate_functions) by adding a `sound` field to the effect table.

#### Example
```lua
return {
	message = localize('k_upgrade_ex'),
	sound = 'MyMod_UpgradeSound',
}
```
```

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

### Customize Initial Deck Creation

Source: https://github.com/steamodded/smods/wiki/Release Notes/1501a

The `initial_deck` option in custom Back objects allows customization of the starting deck. Specify suits and ranks to include or exclude.

```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'},
}
```

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

### Create and Register Example Voucher

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

Demonstrates the creation and registration of a custom 'Voucher' consumable type. This includes defining its name, slug, configuration, position, localization text, cost, and other properties.

```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()
```

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

### Create and Register Example Planet, Tarot, and Spectral

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

Demonstrates the creation and registration of custom 'Planet', 'Tarot', and 'Spectral' consumable types. Ensure all required parameters are provided for each type.

```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()
```

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

### POST /api/apply

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Back

Apply modifiers at the start of a run.

```APIDOC
## POST /api/apply

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

### Method
POST

### Endpoint
`/api/apply`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **back** (object) - The back object.

### Request Example
```json
{
  "back": { ... }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.

#### Response Example
```json
{
  "status": "applied"
}
```
```

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

### Full Context Example with Debuff

Source: https://github.com/steamodded/smods/wiki/Guide-‐-Joker-Calculation

This example illustrates a more complete context object, including the `debuffed_hand = true` flag. This flag is used when a played hand is affected by a blind debuff, such as playing fewer than five cards under the Psychic blind.

```lua
local context = {
   cardarea = G.jokers,
   full_hand = G.play.cards,
   scoring_hand = scoring_hand, -- from G.FUNCS.get_poker_hand_info(..)
   scoring_name = hand_name,    -- from G.FUNCS.get_poker_hand_info(..)
   poker_hands = poker_hands,   -- from G.FUNCS.get_poker_hand_info(..)
   debuffed_hand = true
}
```

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

### Warn Log Output Format

Source: https://github.com/steamodded/smods/wiki/Logging

Example of how warning messages are formatted in the log output.

```log
2024-04-04 22:58:45 :: WARN  :: MyWarnLogger :: This is a warn message
```

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

### Apply Font to Text (All Languages Setting 2)

Source: https://github.com/steamodded/smods/wiki/Text-Styling

This example applies a font with the 'All2' language setting.

```pas
{f:9}Hello{}
```

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

### Apply Font to Text (Japanese)

Source: https://github.com/steamodded/smods/wiki/Text-Styling

This example shows how to apply a font for Japanese text using the {f:index} syntax.

```pas
{f:5}こんにちは{}
```

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

### Simple loc_txt Table Example

Source: https://github.com/steamodded/smods/wiki/Localization

A basic loc_txt table defining a name and a single line of text for an object.

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

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

### Example of Text Node Configuration with ref_table

Source: https://github.com/steamodded/smods/wiki/UI-Guide

Use ref_table and ref_value to dynamically set text for a G.UIT.T node. The text will update when the referenced value changes.

```lua
{
  n = G.UIT.T,
  config = {
    ref_table = G.GAME.current_round,
    ref_value = "reroll_cost",
    scale = 0.75,
    colour = G.C.WHITE
  }
}
```

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

### Trace Log Output Format

Source: https://github.com/steamodded/smods/wiki/Logging

Example of how trace messages are formatted in the log output.

```log
2024-04-04 22:58:45 :: TRACE :: MyTraceLogger :: This is a trace message
```

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

### loc_txt Table with Label and Multi-line Text

Source: https://github.com/steamodded/smods/wiki/Localization

Example of a loc_txt table that includes a 'label' field and a multi-line description.

```lua
{
    ['en-us'] = {
        -- Sometimes, more text is required than just a name and a description
        label = 'Label',
        name = 'Name',
        text = { 'A moderately long',
 'description of',
 'your effect.' },
    }
}
```

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

### Apply Font to Text (Simplified Chinese)

Source: https://github.com/steamodded/smods/wiki/Text-Styling

This example shows how to apply a font for Simplified Chinese text using the {f:index} syntax.

```pas
{f:2}Hello, 你好{}
```

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

### SMODS.Back.apply Method

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Back

Use the `apply` method to apply modifiers at the beginning of a run. If you need to modify the starting deck, this must be achieved through events.

```lua
apply(self, back)
```

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

### Get Directory Items Info

Source: https://github.com/steamodded/smods/blob/main/libs/nativefs/README.md

Retrieves detailed information for all items within a specified directory. This is more efficient than calling getInfo for each item individually.

```lua
local nativefs = require("nativefs")

-- Prints all information on files in C:\\Windows
local files = nativefs.getDirectoryItemsInfo("C:/Windows")
for i = 1, #files do
  if files[i].type == "file" then
    local info = nativefs.getInfo("C:/Windows/" .. files[i].name)
    print(i .. ": " .. files[i] .. " : Type:" .. info.type .. ", Size:" .. tostring(info.size) .. ", last modified:" .. tostring(info.modtime))
  end
end
```

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

### Adding a Single Description to Localization File

Source: https://github.com/steamodded/smods/wiki/Localization

Example of a localization file containing a single description for a Joker card. It shows how to define the name, text (which can be multi-line), and unlock conditions.

```lua
return {
    descriptions = {
        -- this key should match the set ("object type") of your object,
        -- e.g. Voucher, Tarot, or the key of a modded consumable type
        Joker = {
            -- this should be the full key of your object, including any prefixes
            j_mod_joker = {
                name = 'Name',
                text = {
                    'This is the first line of this description',
                    'This is the second line of this description',
                },
                -- only needed when this object is locked by default
                unlock = {
                    'This is a condition',
                    'for unlocking this card',
                },
            },
            -- multiple line name and multiple description box example
            j_mod_multi_joker = {
                name = {
                    'First line of name',
                    'Second line of name',
                },
                text = {
                    {
                       'First line of box 1',
                       'Second line of box 1',
                    },
                    {
                       'First line of box 2',
                       'Second line of box 2',
                    }
		}
            },
        },
    },
}
```

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

### Advanced Node Configuration Example

Source: https://github.com/steamodded/smods/wiki/UI-Guide

Illustrates advanced node configuration options such as custom IDs, instance types for layering, reference tables for data, function callbacks for drawing and clicks, and tooltips.

```lua
{
  id = "my_custom_node",
  instance_type = "UIBOX",
  ref_table = G.some_data_table,
  ref_value = "some_key",
  func = "draw_my_node_content",
  button = "handle_my_node_click",
  tooltip = {
    title = "My Tooltip",
    text = {"Line 1", "Line 2"}
  },
  detailed_tooltip = {
    title = "Detailed Info",
    text = {"More details here"}
  }
}
```

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

### Create Custom CardArea in SMODS

Source: https://github.com/steamodded/smods/wiki/Release Notes/1221a

Use this function on your Mod Object to create a custom CardArea at the correct point of the run start sequence. This ensures proper loading. The example below creates a new CardArea 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
```

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

### Define Poker Hand Example

Source: https://github.com/steamodded/smods/wiki/SMODS.PokerHand

Example of defining a poker hand with various card types, scoring conditions, and custom editions/enhancements. This format is used for the 'example' parameter in SMODS.PokerHand.

```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
}
```

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

### Set Balatro Launch Options in Steam

Source: https://github.com/steamodded/smods/wiki/Installing Steamodded linux

Configure Steam launch options to correctly integrate Lovely with Balatro. This ensures that the game launches with the necessary DLL overrides.

```bash
WINEDLLOVERRIDES="version=n,b" %command%
```

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

### Check if a Mod is Installed in Lua

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

Verify if another mod is installed and loaded by using SMODS.find_mod. The presence of a result indicates the mod is active.

```lua
-- Check if mod is installed
if next(SMODS.find_mod('OtherMod')) then
  -- OtherMod is present and loaded
end
```

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

### Debug Log Output Format

Source: https://github.com/steamodded/smods/wiki/Logging

Example of how debug messages are formatted in the log output. Note: The example output shows TRACE, which might be a typo in the source.

```log
2024-04-04 22:58:45 :: TRACE :: MyDebugLogger :: This is a debug message
```

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

### Building UI Layout with Node Types

Source: https://github.com/steamodded/smods/wiki/UI-Guide

Demonstrates constructing a UI layout using nested Row and Column nodes with specific configurations for size, alignment, and color. This example showcases how different node types combine to form complex structures.

```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}}
		}}
	}}
}}
```

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

### Get Random Rank with Pseudorandom Element

Source: https://github.com/steamodded/smods/wiki/SMODS.Rank-and-SMODS.Suit

Feed `SMODS.Ranks` directly into `pseudorandom_element` to get a random rank while respecting `in_pool` rules. Requires a pseudoseed for reproducibility.

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

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

### Conditional Card Inclusion in Starting Decks

Source: https://github.com/steamodded/smods/wiki/SMODS.Rank-and-SMODS.Suit

Use `in_pool(self, args)` with `args.initial_deck` to define rules for adding cards to starting decks independently of other pool inclusions.

```lua
card.in_pool(args)
args.initial_deck
```

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

### JimboQuip Filter Configuration Example

Source: https://github.com/steamodded/smods/wiki/SMODS.JimboQuip

Configure when a JimboQuip is allowed to appear and control its display frequency. The filter function can return a weight to influence the quip's probability and override base checks.

```lua
filter = function(self, type)
    if next(SMODS.find_card('j_hanging_chad')) then
        return true, {weight = 10}
    end
end
```

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

### Create a Button with Text Formatting Tag

Source: https://github.com/steamodded/smods/wiki/Release Notes/1501a

Use the "{button:example_button}" tag within text to create a button that calls a specified function. Ensure the referenced function exists in G.FUNCS.

```lua
"{button:example_button}Click me!"
```

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

### Fatal Log Output Format

Source: https://github.com/steamodded/smods/wiki/Logging

Example of how fatal messages are formatted in the log output.

```log
2024-04-04 22:58:45 :: FATAL :: MyFatalLogger :: This is a fatal message
```

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

### JimboQuip Play Sounds Method

Source: https://github.com/steamodded/smods/wiki/SMODS.JimboQuip

Provides precise control over sound playback for JimboQuips, overriding any sounds defined in the 'extra' table.

```lua
play_sounds(self, times)
```

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

### Create Custom Badge with Specific Colors and Scaling

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Booster

This example shows how to create a custom badge with specified text, background color, text color, and scaling. The `create_badge` function is used for this purpose.

```lua
badges[#badges+1] = create_badge(localize('k_your_string'), G.C.RED, G.C.BLACK, 1.2 )

```

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

### Error Log Output Format

Source: https://github.com/steamodded/smods/wiki/Logging

Example of how error messages are formatted in the log output.

```log
2024-04-04 22:58:45 :: ERROR :: MyErrorLogger :: This is an error message
```

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

### Handle SMODS Initialization in 1.0.0+

Source: https://github.com/steamodded/smods/wiki/02.-Migration-guide

In version 1.0.0+, SMODS.INIT is removed. Move all code previously inside SMODS.INIT to the top-level scope.

```lua
SMODS.INIT
```

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

### Weight System

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Edition

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

```APIDOC
## Weight System

### Default Edition Weights
- `negative`: 3
- `polychrome`: 3 (takes negative's weight in some circumstances)
- `holographic`: 14
- `foil`: 20

### Spawn Chance Calculation
The base chance for an edition to appear in the shop is 4%. With the default weights, this results in a 2% chance for a foil joker to appear.

Custom editions added to the shop maintain this 4% base chance. If you add an edition with a weight of 40, its spawn chance will be reduced accordingly (e.g., 2% chance for the custom edition, reducing foil to 1%).

### Hone and Glow Up Vouchers
These vouchers adjust the weights of base game editions:
- 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 vouchers. To include your custom edition in this functionality, implement the `get_weight` method as follows:

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

This ensures your custom edition's weight is scaled by `G.GAME.edition_rate`, which is modified by the vouchers.
```

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

### Create Shop Card Context Variables

Source: https://github.com/steamodded/smods/wiki/Calculate-Functions

Provides variables for creating a shop card. context.set specifies the card set, and shop_create_flags can be returned to alter the card creation process.

```lua
context.create_shop_card -- flag to identify this context, always TRUE
context.set -- The selected set of the card that is to be created
```

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

### Get Size of Item Pool

Source: https://github.com/steamodded/smods/wiki/Utility

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

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

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

### Get Optional Features

Source: https://github.com/steamodded/smods/wiki/Internal-Documentation

Inserts all enabled optional features from injected mods into the `SMODS.optional_features` table.

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

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

### JimboQuip Constructor

Source: https://github.com/steamodded/smods/wiki/SMODS.JimboQuip

This section describes the JimboQuip constructor and its parameters for creating new quips.

```APIDOC
## SMODS.JimboQuip

### Description
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** (string) or localization entry - The text to display. If using localization, 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 [reference](https://github.com/Steamodded/smods/wiki/API-Documentation#common-parameters).
- **dependencies** (table) - Dependencies for the quip. See [reference](https://github.com/Steamodded/smods/wiki/API-Documentation#common-parameters).
- **type** (string) - Specifies if it's a 'win' or 'loss' quip. Can be other strings for modded types.
- **extra** (table) - A table of parameters to customize the quip's appearance and behavior. Can also be a function that returns the appropriate 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 the materialize effect.
  - **text_key** (string) - Key override for the quip text.
  - **times** (number) - Number of times to play sounds.
  - **pitch** (number) - Pitch of the sounds.
  - **sound** (string or table) - String or table of strings for sounds to play.
  - **juice** (table) - Arguments to pass into `card:juice_up`.
  - **delay** (number) - Delay for the next loop of sounds.

### Request 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
})
```
```

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

### Creating an Interactive UIBox

Source: https://github.com/steamodded/smods/wiki/UI-Guide

Shows how to create a UIBox, a fundamental component for interactive UIs in Balatro. A UIBox is updated by recreating it with new values, making it suitable for dynamic menus.

```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}}
```

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

### Get Attribute Pool

Source: https://github.com/steamodded/smods/wiki/SMODS.Attributes

Use SMODS.get_attribute_pool to retrieve a table of center keys that possess a specified attribute.

```lua
SMODS.get_attribute_pool(attribute) -> table
```

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

### SMODS.Back Initialization Parameters

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Back

When initializing a SMODS.Back object, you must provide a localization key and either a text localization entry or a reference to one. Optional parameters include atlas and position for texture application, and various configuration options for gameplay effects and display.

```lua
-- Required parameters:
-- key, loc_txt or localization entry

-- Optional parameters (defaults):
-- atlas = 'centers', pos = { x = 0, y = 0 }
-- config = {}, unlocked = true, discovered = false, no_collection, prefix_config, dependencies, display_size, pixel_size
-- initial_deck: { ranks, suits, exclude = false }
```

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

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

Source: https://github.com/steamodded/smods/wiki/Release Notes/1501a

Initialize a SMODS.ScreenShader to apply custom effects to the entire game screen. The 'should_apply' function determines when the shader is active, and 'send_vars' passes game data to the shader.

```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,
})
```

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

### Customize JimboQuip Appearance and Sound

Source: https://github.com/steamodded/smods/wiki/Release Notes/0827

Use the `extra` table to customize quip visuals and sounds. Specify cards to show (`center`), particle and materialize colors, a custom text key, sound playback count (`times`), pitch, sound effect name (`sound`), juice effect parameters (`juice`), and delay between sound loops.

```lua
extra = {
	center = 'j_hanging_chad', -- key of card to show
	particle_colours = { -- table of up to 3 colours for particles
		G.C.GREEN,
		G.C.PURPLE,
		G.C.GOLD
	},
	materialize_colours = { -- table of up to 3 colours for materialize effect
		G.C.GREEN,
		G.C.PURPLE,
		G.C.GOLD
	},
	text_key = 'modprefix_example_quip_newkey', -- key override for the quip
	times = 5, -- number of times to play sounds
	pitch = 1, -- pitch of sounds
	sound = 'voice1', -- string of sound to play, this can also be a table of strings to play simultaneously,

juice = {0.3, 0.7}, -- table of args to pass into card:juice_up
	delay = 0.13, -- amount to delay the next loop of sounds
}
```

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

### Check for 'setting_blind' context

Source: https://github.com/steamodded/smods/wiki/Calculate-Functions

Use this condition to trigger effects when the blind is started. 'context.setting_blind' is a boolean flag that is always TRUE.

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

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

### Apply Font to Text (None Language Setting)

Source: https://github.com/steamodded/smods/wiki/Text-Styling

This example applies a font with the language setting explicitly set to 'None'.

```pas
{f:7}Hello{}
```

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

### Buying Card Context Variables

Source: https://github.com/steamodded/smods/wiki/Calculate-Functions

Provides variables related to buying a card. context.card holds the bought card, and context.buying_self is a recommended flag to ensure you are evaluating the card being bought.

```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
```

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

### Access Event Manager via G.E_MANAGER

Source: https://github.com/steamodded/smods/wiki/G

Use G.E_MANAGER to access the event manager. Refer to the Event Manager guide for more details.

```lua
G.E_MANAGER
```

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

### Create Booster Pack with Foil Jokers

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Booster

This example demonstrates creating a booster pack specifically for foil jokers. It includes parameters like `soulable`, `key_append`, and `edition` for custom card 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,
```

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

### Apply Font to Text (Traditional Chinese)

Source: https://github.com/steamodded/smods/wiki/Text-Styling

This example demonstrates applying a font for Traditional Chinese text with the {f:index} syntax.

```pas
{f:3}Hello, 您好{}
```

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

### Register Custom Music Track with Priority

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

Load a custom music track and define logic for when it should play, with higher return values indicating higher priority.

```lua
-- Register a custom music track
SMODS.Sound {
  key = 'music_boss_custom',
  path = 'boss_music.ogg',
  pitch = 0.7,
  volume = 0.6,

  -- Control when this music plays
  select_music_track = function(self)
    if G.GAME and G.GAME.blind and G.GAME.blind.boss then
      -- Return higher number to take priority
      return 100
    end
    return nil
  end
}
```

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

### SMODS.CanvasSprite Initialization and Parameters

Source: https://github.com/steamodded/smods/wiki/SMODS.CanvasSprite

Explains how to create a CanvasSprite and the available parameters for customization.

```APIDOC
## SMODS.CanvasSprite

### Description
This class extends Balatro's `Sprite` object, and creates a Sprite that renders the contents of a Love2D Canvas. Note that unlike vanilla Sprites, creating a CanvasSprite uses a single table as the argument.

Once a CanvasSprite is created (e.g. `local sprite = SMODS.CanvasSprite { ... }`), the object will contain a `canvas` object, which is the Love2D canvas itself (e.g. `sprite.canvas`). This is where everything should be rendered.

### Parameters
#### Optional parameters *(defaults)*:
- **X, Y, W, H** (number) - `0, 0, G.CARD_W, G.CARD_H` - the vanilla Sprite position and dimension parameters.
- **canvasW, canvasH** (number) - `71, 95` - the width and height of the Love2D canvas in pixels.
- **canvasScale** (number) - `10` - a multiplier applied to the canvas dimensions; higher numbers help make the image sharper.
- **text** (string) - `""` - the string to be rendered.
- **text_offset** (table) - `{ x = 0, y = 0 }` - controls the position of the center of the whole string of text. The origin is the top-left of the canvas.
- **text_colour** (Color) - `G.C.UI.TEXT_LIGHT` - controls the color of the text itself.
- **text_width** (number) - `canvasW` - scales the text by specifying its width in pixels.
- **text_height** (number) - `canvasH` - scales the text by specifying its height in pixels.
- **ref_table** (table) - nil - If set along with `ref_value`, uses `ref_table[ref_value]` as the text string.
- **ref_value** (any) - nil - If set along with `ref_table`, uses `ref_table[ref_value]` as the text string.
- **text_font** (number) - `1` - the key of a font in `SMODS.Fonts` or the index of a font in `G.FONTS`.
- **text_transform** (table) - nil - A table containing transformation parameters for `love.graphics.draw`.

### Request Example
```lua
local sprite = SMODS.CanvasSprite {
    X = 10,
    Y = 10,
    canvasW = 100,
    canvasH = 100,
    canvasScale = 5,
    text = "Hello World",
    text_colour = G.C.RED
}
```

### Response
#### Success Response (200)
- **canvas** (Canvas) - The Love2D canvas object associated with this sprite.
```

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

### Define Localization for Joker Description

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

Set up localized names and descriptions for custom Jokers. This example shows how to define text that includes variables.

```lua
-- localization/en-us.lua
return {
  descriptions = {
    Joker = {
      j_mam_flush_master = {
        name = 'Flush Master',
        text = {
          'Gains {C:red}+#2#{} Mult',
          'when you play a {C:attention}Flush{}',
          '{C:inactive}(Currently {C:red}+#1#{C:inactive} Mult)'
        }
      }
    },
    Tarot = {
      c_mam_chaos_shuffle = {
        name = 'Chaos Shuffle',
        text = {
          'Convert up to {C:attention}#1#{}',
          'selected cards to random suits'
        }
      }
    }
  },
  misc = {
    dictionary = {
      k_mam_upgraded = 'Upgraded!'
    },
    labels = {
      crystal_seal = 'Crystal'
    }
  }
}
```

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

### SMODS.Enhancement: set_badges Example

Source: https://github.com/steamodded/smods/wiki/SMODS.Center/SMODS.Enhancement

Adds custom badges to a card using the `create_badge` function. Appends to the existing `badges` table to avoid overwriting.

```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,
}
```

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

### Get Clean Pool of Items

Source: https://github.com/steamodded/smods/wiki/Utility

Wrapper for get_current_pool that excludes unavailable items, providing a list of valid keys only. Can optionally append arguments.

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

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

### Define localized sound paths

Source: https://github.com/steamodded/smods/wiki/SMODS.Sound

Use a table to specify different sound files for different languages. The 'default' key is used if no specific language match is found.

```lua
path = {
	['default'] = 'my_sound.ogg',
	['nl'] = 'my_sound-nl.ogg',
	['pl'] = 'my_sound_pl.ogg',
}
```