JokerComboAdvisor/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

"Joker Combo Advisor" — a Steamodded (SMODS) mod for Balatro that scores shop/pack jokers against the player's current jokers, shows a "Combo Advisor" tooltip on hover, and pulses strongly recommended cards. Pure Lua, no build step.

Commands

Syntax check everything:

luac -p main.lua synergies.lua config.lua

There is no test framework. Test the engine standalone by stubbing the game globals before loading main.lua (the game itself cannot be launched headlessly here):

lua - <<'EOF'
SMODS = { load_file = function(f) return loadfile(f) end,
          current_mod = { config = dofile('config.lua') } }
Card = { generate_UIBox_ability_table = function() end, update = function() end }
G = { UIT = {ROOT='ROOT', R='R', T='T'},
      C = { UI = {TEXT_DARK='dark'}, GREEN='green', CLEAR='clear' },
      STAGES = {RUN=1}, FUNCS = {} }
dofile('main.lua')
print(JCA.score('j_baron', 'j_mime'))            -- pairwise score
-- simulate owned jokers via G.jokers.cards; each card needs
-- { config = { center = { key=..., name=..., set='Joker' } } }
EOF

Expected score tiers: famous explicit pair + tags ≈ 6, hand-type/suit cluster = 4, single tag match = 2, generic mult+xmult complement = 1, unrelated = 0.

In-game verification (this machine)

• The mod is symlinked into the live Mods folder: ~/.local/share/Balatro/Mods/JokerComboAdvisor -> ~/Documents/Balatro Mod. Edits here go live on next game launch — do not copy files anywhere.
• Game: Steam/Proton at /mnt/games/Steam/steamapps/common/Balatro (note: second Steam library, not the default paths). Lovely injector + Steamodded 1.0.0-beta are already installed; mods are managed via Balatro Mod Manager.
• Crash/load logs: ~/.local/share/Balatro/Mods/lovely/log/ (newest file).
• Remote: https://git.aleshym.co/funman300/JokerComboAdvisor (private, user's Gitea). Pushes authenticate via the repo-local credential helper, which reads the token from ~/.config/tea/config.yml at push time — never copy the token into the repo or the remote URL. Commit per feature.

Architecture

Three-layer split; JCA is the single global namespace:

• synergies.lua — data only. Returns { jokers = {...}, pairs = {...} }. Each of the 150 vanilla jokers gets gives (capabilities it adds) and wants (capabilities that strengthen it) tag lists, converted to sets at the bottom of the file. PAIRS lists famous explicit combos worth a flat +4.
• main.lua — engine + game integration:
  • Scoring: JCA.score(a, b) = explicit pair bonus (+4) + 2 per give→want tag match in each direction + 1 for the generic "+Mult/+Chips source with an ×Mult joker" complement (second return value flags when that +1 applied). JCA.partners_for(card) aggregates over G.jokers.cards; total ≥ JCA.config.threshold ⇒ recommended. The generic +1 counts toward the total once per candidate, not per owned joker — since tag/pair scores are even and the threshold is 4, the generic bonus alone can never trigger a recommendation, so a pulsing card always has a nameable partner. Jokers whose multiplier the generic rule misreads opt out with {no_generic = true} in synergies.lua (Joker Stencil: its ×Mult grows with empty slots, so "+Mult jokers feed it" is backwards).
  • UI hooks: wraps Card:generate_UIBox_ability_table to append a tooltip entry to aut.info (format: array of rows-of-UIT-nodes plus a .name string — must match what vanilla info_tip_from_rows expects), and wraps Card:update for the ~2.5s pulse on recommended shop cards and the partner highlight (hovering a joker juices its owned partners ~0.9s; partner set cached on the card as jca_hl, dropped when hover ends). All hook bodies are pcall-wrapped so a scoring bug can never crash a run — keep it that way.
  • Sell advisor: JCA.weakest_link() (full board + ≥3 jokers + a strict minimum required, else nil) flags the lowest-total owned joker with a red verdict row; suppressed by learning mode, toggled by config.sell_advisor.
  • Public API for other mods: JCA.register(key, gives, wants, opts), JCA.register_pair(a, b, blurb) (sets JCA._pairs_dirty so the Combos tab re-sorts), JCA.register_clash(a, b, warning). Unknown tags are dropped with a log line, never an error.
  • Config tab: registered on SMODS.current_mod.config_tab, guarded by if SMODS.current_mod so standalone tests don't need full stubs.
  • Synergy catalog: SMODS.current_mod.extra_tabs adds Combos/Engine/ Economy/Hands tabs (plus a text-only Progress tab with discovery completion bars) that render real Card objects in CardAreas (collection-style, so hover shows each joker's own tooltip). One theme per page; pagers swap the tab_contents UIBox from an option-cycle callback — the same pattern as SMODS's achievements tab. Because pages contain live Card/CardArea objects, tab definitions must be rebuilt on every call — never cache the node trees. The same tabs open in-run via a "Combos" HUD button (wrapped create_UIBox_HUD, injected into the button_area node under Run Info/Options); the pagers work there because vanilla create_tabs also names its body tab_contents.
  • Discovery: CardArea:emplace hook calls JCA.check_discoveries when a joker lands in G.jokers; famous pairs fielded together persist in config.discovered (saved immediately via SMODS.save_mod_config) and per-run in G.GAME.jca_run_combos. Undiscovered pairs render face-down with a ??? caption in the Combos tab; blurb replaces it once fielded. Themes (every theme_info tag) persist in config.themes_found once two DIFFERENT jokers connect the tag (giver + wanter; a joker carrying both sides needs a second joker). One toast per emplacement, famous pair outranking theme. Badge/progress render in theme_tab_def; toast names come from JCA.theme_names (filled after THEME_TABS, used only at gameplay time).
  • Post-run recap: wraps create_UIBox_game_over/create_UIBox_win and inserts a "Combos fielded this run" row (from G.GAME.jca_run_combos) relative to vanilla button ids (from_game_over; from_game_won or win_cta) via a parent-trail walk — anchor depths differ per screen.
  • Learning mode (config.learning_mode): suppresses the pulse and the "Strong pick!" line but never the explanations. No-synergy buy-area tooltips show "Looking for:"/"Offers:" hints from TAG_LABEL. synergies.lua also exports theme_info (one teaching sentence per catalog tag — keep ≤ ~90 chars and cover every THEME_TABS tag).
  • The real (Lovely-patched) game source is readable at ~/.local/share/Balatro/Mods/lovely/dump/ — check it before assuming what a vanilla function returns or expects.
• config.lua — default settings (pulse, owned_tooltip, threshold). Steamodded loads and persists this table itself; read it only via SMODS.current_mod.config (exposed as JCA.config).

Conventions and gotchas

• Cluster tags (hand types pair/straight/flush/…, suits, planet, spectral_gen): put the same tag in both gives and wants of every member so members mutually reinforce (2+2 = 4). Pure enablers (e.g. Four Fingers, Smeared, Pareidolia) only give; pure payoffs only want.
• Every wants tag must be given by at least one joker — the standalone test's orphan-tag check enforces this idea; re-run it after database edits.
• Tooltips teach: JCA.explain(hovered, partner) picks one reason per partner — famous-pair blurb (third element of each PAIRS entry), else the first TAG_ORDER match phrased from TAG_TEXT (give/want/both variants), else the generic mult×xmult line. Every non-engine tag (anything besides mult/chips/xmult) MUST have a TAG_TEXT entry; new PAIRS entries need a blurb under ~34 chars so name + blurb fits one tooltip row.
• Vanilla center keys contain intentional misspellings/abbreviations — do not "fix" them: j_gluttenous_joker, j_selzer, j_ticket (Golden Ticket), j_trousers (Spare Trousers), j_ring_master (Showman), j_caino (Canio), j_delayed_grat, j_todo_list.
• Unknown joker keys (from other mods) must keep scoring 0 — never index JCA.db[key] without a nil guard.
• Display names go through localize{type='name_text', set='Joker', ...} with a pcall + center.name fallback.
• Anti-synergies never affect scores. Known traps are warning-only data: CLASHES (pairwise, red "Clashes -" tooltip line vs owned jokers) and CAUTIONS (per-joker, buy-area "Caution:" line) in synergies.lua, same ~34-char blurb budget as PAIRS. Learning mode keeps warnings visible.
• The UI hooks are the only untested-in-game surface; if a tooltip regression is reported, suspect the aut.info entry format first and check the lovely log.