JokerComboAdvisor/README.md

# Joker Combo Advisor

A [Steamodded](https://github.com/Steamodded/smods) mod for Balatro that
recommends joker combos while you play:

- **Hover any joker in the shop or a Buffoon Pack** and a *Combo Advisor*
  tooltip appears next to its description, naming which of your current
  jokers it synergizes with **and why** ("Mime: retriggers cards in hand"),
  so you learn the mechanics rather than just the verdict. Famous pairs get
  hand-written explanations; everything else is phrased from the synergy
  tags. Jokers with no current synergy teach instead what to pair them with
  ("Looking for: Tarot cards" / "Offers: face cards"). Strong picks also get
  a "Strong pick for this build!" callout and **pulse periodically** in the
  shop so you can spot them without hovering.
- **Combo discovery**: the first time you field a famous pair together, a
  "New combo!" toast fires and the pair is permanently inked into the
  catalog — until then its cards sit face-down with a "???" caption, so
  filling in the Combos tab becomes its own collection hunt.
- **Theme discovery**: assembling any synergy theme for the first time —
  one joker that provides it plus another that wants it — fires a
  "Theme explored!" toast, badges that theme's catalog page, and counts
  toward a per-tab progress line ("3 of 10 themes explored").
- **Hover a joker you own** to see its active combos with the rest of your
  lineup.
- **Browse the synergy catalog** any time: a purple **Combos** button in the
  run HUD (under Run Info / Options) opens it in an overlay, and the same
  tabs live under Mods > Combo Advisor. The *Combos* tab shows the famous
  pairs as card duos with their explanation once fielded; *Engine* /
  *Economy* / *Hands* tabs page through each synergy theme with a one-line
  explanation of the mechanic and its **Sources** and **Payoffs** as real
  cards — hover any card for its normal description tooltip. All of it is generated
  from the same database the advisor scores with. Jokers you haven't
  discovered yet show face-down (no spoilers) unless the profile has used
  the game's own **Unlock All** setting, in which case everything is shown.
- **Post-run combo recap**: the win and game-over screens list the famous
  pairs you fielded during that run.

## How recommendations work

`synergies.lua` tags all 150 vanilla jokers with what they *give* a build
(e.g. `retrig_scoring`, `gold_gen`, `xmult`) and what they *want*
(e.g. `faces`, `probability`, `money`). Two jokers score:

| Signal | Points |
| --- | --- |
| Famous explicit pair (Baron + Mime, Midas Mask + Golden Ticket, …) | +4 |
| Each *gives* tag the other *wants* (both directions) | +2 |
| Generic engine complement (+Mult/+Chips source with an ×Mult joker) | +1 |

A shop joker is *recommended* (pulses) when its total score against your
owned jokers reaches the configured threshold (default 4). Partners with a
pairwise score of 2+ are listed in the tooltip, strongest first.

## Settings

In-game: **Mods > Combo Advisor > Config**. Changes persist across sessions.

- **Pulse recommended jokers in shop** — turn the visual pulse on/off.
- **Show combo tooltip on owned jokers** — the "Active combos" section on
  jokers you already hold.
- **Learning mode** — hides the verdicts (pulse and "Strong pick!") while
  keeping all the explanations, for players who want to learn the synergies
  rather than be told what to buy.
- **Recommendation threshold** — 2 (chatty) to 8 (only slam-dunk combos).

Defaults live in `config.lua`.

## Installation

1. Install [Lovely](https://github.com/ethangreen-dev/lovely-injector) and
   [Steamodded](https://github.com/Steamodded/smods) (follow their READMEs).
2. Copy this whole folder into your Balatro `Mods` directory:
   - **Windows:** `%AppData%/Balatro/Mods/`
   - **Linux (Steam/Proton):**
     `~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/`
     (or the same path under `~/.steam/steam/`, or
     `~/.var/app/com.valvesoftware.Steam/.local/share/Steam/...` for Flatpak Steam)
   - **macOS:** `~/Library/Application Support/Balatro/Mods/`
3. Launch Balatro. The mod should appear in the in-game **Mods** menu.
   If something goes wrong, check the Lovely log
   (`Mods/lovely/log/` next to the game, or the console window on launch).

## Extending it

- **Add or fix a synergy:** edit `synergies.lua`. Give a joker a tag with
  `j('j_key', {gives...}, {wants...})`, or add a famous pair to the `PAIRS`
  table at the bottom. Modded jokers can be added the same way using their
  full key (e.g. `j_mymod_cooljoker`) — unknown jokers simply score 0.
- **From another mod:** if your mod adds jokers, teach the advisor about
  them at load time (any point after Combo Advisor has loaded):

  ```lua
  if JCA then
      -- gives/wants use the tag names from synergies.lua
      JCA.register('j_mymod_cooljoker', {'xmult'}, {'faces'})
      -- optional: opts {no_generic = true} if the generic
      -- "+Mult feeds the multiplier" logic misreads your joker
      JCA.register('j_mymod_slotless', {'xmult'}, nil, {no_generic = true})
      -- famous pair (+4, discoverable, shown in the Combos tab);
      -- keep the blurb under ~34 characters
      JCA.register_pair('j_mymod_cooljoker', 'j_pareidolia',
          'every card becomes a face for it')
      -- known trap: warning-only red tooltip line
      JCA.register_clash('j_mymod_cooljoker', 'j_vampire',
          'drains the enhancements it needs')
  end
  ```

  Unknown tags are dropped with a `JCA:` log line instead of erroring, so
  a typo in your registration can never break a load.
- **Tune sensitivity:** use the in-game Config tab, or change the defaults
  in `config.lua`.

## Files

| File | Purpose |
| --- | --- |
| `JokerComboAdvisor.json` | Steamodded mod metadata |
| `main.lua` | Scoring engine, hover tooltip, shop pulse, config tab |
| `synergies.lua` | Tag database for all 150 vanilla jokers + famous pairs |
| `config.lua` | Default settings (persisted by Steamodded once changed in-game) |