Final Boss

Bosses talk back. Every boss blind gets a short line of dialogue when it starts, reacts to your big hands, close calls and last hand, and gloats if you lose to it. Showdown bosses go further: a roaming boss avatar with an HP bar, a cinematic intro, their own music, screen effects and a slow-motion explosive finale. You also decide when showdowns appear, so you can have a final boss every 8 antes like vanilla or much sooner.

Requirements

• Balatro 1.0.1
• Lovely 0.9.0 or newer
• Steamodded 26.829.0 or newer

Install

1. Download FinalBoss-v1.0.0.zip from the releases page.
2. Extract it into %AppData%\Balatro\Mods\ so the files end up in %AppData%\Balatro\Mods\FinalBoss\.
3. Start Balatro. The mod appears in the Mods menu as "Final Boss" with its own config tabs.

Features

Encounter tiers

Every boss blind gets a tier. The tier decides how much of the show it gets.

Reaction triggers:

• Big hand: a single hand scores at least 30% of the blind requirement.
• Close: your running total is at least 75% of the requirement but you have not won yet.
• Last hand: you have no hands left and have not reached the requirement.
• Disabled: the boss was disabled (for example by Chicot).
• Defeat: the hand that reaches the requirement.

If several reactions would fire on the same hand, only one plays (last hand, then close, then big hand). Click the blind chip or press any key during an intro to advance to the next line; press twice quickly to skip the rest of the intro.

Interrupting the boss. Play a hand while the boss's intro is still running (the showdown title card or any intro line) and the speech stops at once: the boss snaps (a sharp shake and a red flash on the avatar, or on the HUD chip for regular bosses) and says its interrupted line instead. That line replaces the reaction line for that hand; the hit itself still lands. It happens once per blind. Skipping lines with a key or a click, or discarding, is not an interruption.

Game over. When a boss beats you, Jimbo mocks you on the game-over screen with that boss's catchphrase.

Regular bosses are light tier from the ante set in min_ante onward. Showdown bosses are always full tier. Mods can override the tier per boss (see below). An explicit 'light' or 'full' tier ignores min_ante and whether the boss is a showdown.

Showdown stage

Showdowns (full tier) get a stage of their own. None of it appears for regular bosses.

• Roaming boss avatar. A large chip with the boss's own art sits on the table. It bobs and lives right of the play area, above the deck; while you choose cards it glides between a few open spots where its HP bar stays clear of your cards, and it stops while it talks. When you play a hand it returns to the right of the play area until the hand resolves. Its speech bubbles are drawn above your cards. The boss reacts when your score lands: each hand makes it flash and flinch, a hand under 10% of the boss's health makes it shrug off the hit and laugh (a distinct "ha-ha-ha": it hops and tilts, and its line waits until the laugh ends), and it gets wounded: below 50% it cracks and bobs faster, below 25% it cracks more and trembles. While the boss is on the table, its HUD chip steps out of the HUD and returns when it leaves. Click it to skip an intro line.
• HP bar and damage numbers. Under the avatar: the boss name, a vanilla-style pixel bar (the same rounded, stepped bars as the game's own progress bars) in the boss's colour and remaining / max. The bar is drawn under your cards, so a card that overlaps it stays on top; damage numbers and speech bubbles still draw above. Each hand drops the bar at once and leaves a white trail that drains, and a damage number pops up above the avatar (big hands bigger, tiny hands small and grey). The bar flashes at 50% and 25%.
• Cinematic intro. Black bars slide in, a dark band with the "SHOWDOWN" title and the boss name slams in across the screen (above the boss-effect text) and holds for a moment, and the avatar falls onto the table before it speaks. Press any key to jump straight to the avatar and its dialogue (a click works once the avatar has landed). Press again to advance a line; press twice quickly to skip the rest. The title card draws above your cards. Continue never replays the intro.
• Slow-motion explosive finale. When the winning score lands, the game slows for under a second while the avatar cracks and shows its defeat line, then it explodes into shards with a flash in the boss's colour (the flash needs fx). Playing a hand during the title card cuts the intro: the avatar lands at once, snaps at you and says its interrupted line (no intro dialogue).
• Game-over gloat. Lose a showdown and the HP bar goes away (the fight is over) while the avatar glides beside the game-over panel, above the dark overlay. When Jimbo says the boss's catchphrase, the boss laughs once, then bobs smugly until you start a new run or go to the main menu.
• Living arena. The background swirl takes the boss's colours, pulses on each hand, and darkens and spins faster as the boss gets wounded (below 50%, then below 25%). In the final stretch (below 25%) the music pitches up slightly; the pitch-up needs both fx and music. Everything returns to normal when the blind ends.

Turn off the avatar side with cinematic (avatar, HP bar, damage numbers, intro and finale). The arena follows fx, and the music pitch-up in the final stretch needs both fx and music. If you quit or Continue mid-showdown the stage is rebuilt from the saved score, with no fall-in.

Reduced motion. With Balatro's reduced motion setting on, the stage keeps colours, flashes, the dissolve and the explosion, but drops the movement: no roaming, bob, tilt, tremble, knockback, slide/fall animations, slow motion, arena spin or arena pulses (an interrupted boss only flashes red, and the game-over avatar does not bob). The avatar and bars just appear, the avatar stays right of the play area, and screen shake is off (only the explosion keeps a small jiggle).

Showdown schedule

By default, showdowns appear exactly like vanilla (ante 8, 16, ...). Turn on the schedule in the Showdowns tab and pick a first ante and an interval to get extra showdowns, for example start 4 and every 4 gives antes 4, 8, 12 and so on. The win-ante boss is always a showdown. The tab shows a live ante track (antes 1 to 16, showdown antes lit in crimson with a final-boss chip) and warns ("Hard!") when the first showdown is before ante 4. Changes apply from the next ante's boss roll.

Configuration

Set in the Mods menu (Final Boss). The Config tab groups the boss dialogue settings and the showdown stage toggles, with the developer keys at the bottom; the Showdowns tab holds the schedule; the Credits tab has the links (GitHub, the showdown music, Ko-fi). Steamodded saves your choices; config.lua only holds the defaults.

The dialogue, music, FX and cinematic toggles are independent. Any combination works, for example music and effects with no dialogue.

For mod authors

Bosses added by other mods work with zero effort: a boss with no entry and no lines gets the generic lines automatically, with the boss name filled in. To give your boss its own voice, register an encounter and add localization lines.

if FinalBoss and FinalBoss.register_encounter then
  FinalBoss.register_encounter{blind = 'bl_mymod_boss', tier = 'full', voice = {pitch = 0.8}}
end
-- localization: misc.quips.fb_bl_mymod_boss_intro_1 = {"My line", "here"}

Load order. FinalBoss loads at priority -10, and Steamodded orders mods by priority and then id (dependencies do not change the load order). Keep your mod's priority above -10 (the default 0 is fine) so that FinalBoss exists when your main file runs, or register at runtime (for example from your own calculate or setting_blind) after checking that FinalBoss exists.

Always check that FinalBoss exists first so your mod still works without it. Registering the same blind again overwrites the earlier entry (and logs it).

FinalBoss.register_encounter{...}

Custom music

FinalBoss only bids for its own tracks, so a custom track must be your own SMODS.Sound that bids for itself. The key must contain "music" (a Steamodded requirement), and you pass its full prefixed key in the music field. The audio file lives in your mod's assets/sounds/ folder.

SMODS.Sound{
  key = 'music_boss',
  path = 'boss.ogg',
  volume = 0.6,
  pitch = 1,
  select_music_track = function(self)
    local st = G.GAME and G.GAME.FinalBoss
    if st and st.encounter and st.encounter.track == self.key and not st.encounter.ended then
      return 10 -- beats vanilla boss music
    end
  end,
}
FinalBoss.register_encounter{blind = 'bl_mymod_boss', tier = 'full', music = 'MyMod_music_boss'}

The FinalBoss.config.music toggle only silences FinalBoss's own tracks; honour it in your bid if you want players to be able to turn your track off too.

Line keys

All text lives in misc.quips in your mod's localization. Each moment can have as many variants as you like: write _1, _2, _3, ... with no gaps and FinalBoss finds them all. Variants are picked at random, never repeating the previous one when there are two or more.

<blind> is the full blind key, for example bl_hook. For each moment FinalBoss tries the boss-specific key first, then fb_generic_<moment>_<n>, and otherwise skips the moment. The shared opener and closer lines have no generic fallback: if none exist, they are skipped. A raw key is never shown to the player. Generic lines receive the boss name as #1#.

Writing tips: each quip is 1 or 2 lines, and each line should stay under about 24 visible characters so it fits the speech bubble. A gloat line is spoken by Jimbo on the game-over screen, mocking you with the boss's catchphrase: write only the line itself (no "Name:" header, no quotation marks) and no placeholders.

Compatibility

• Big-number scores (Talisman) are converted to plain numbers before FinalBoss compares them, but this path has not been playtested.
• FinalBoss ships one Lovely patch (lovely/timescale.toml) for the finale's slow motion; if a game update changes its target line, the finale simply runs at normal speed.
• Mods that replace (rather than wrap) SMODS.is_showdown_ante or end_round override FinalBoss's behaviour for the showdown schedule and the round-end handling.

Languages

English, German (de), Spanish Latin America (es_419), Spanish Spain (es_ES), French (fr), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Dutch (nl), Polish (pl), Brazilian Portuguese (pt_BR), Russian (ru), Simplified Chinese (zh_CN) and Traditional Chinese (zh_TW). That is 15 localization files. Missing keys fall back to English. Native-speaker corrections are welcome.

Credits

• Author: SirMaiquis
• Showdown music: Balatro (Main Theme) (Orchestral Cover) by Adam Isiah, used with his permission
• Built on Steamodded and Lovely

License

FinalBoss is released under the MIT License. See the changelog for what changed in each release.

Changelog

1.3.0

Bosses react to your tricks.

The fear scale

• The boss watches your score climb, card by card. Past 2×, 10× and 100× the requirement it gets sore, scared, then terrified, and says so on the spot; a higher tier replaces the bubble.
• At 10× its chip (or the showdown avatar) starts to tremble; at 100× the screen shakes and flashes and the boss cowers. The showdown avatar shakes harder at higher tiers.
• A fear line replaces the defeat line. A nemesis keeps its own defeat line.
• This replaces the old overkill line.

Tiered deaths

• 2×: a short slow motion. A regular boss's chip cracks and shatters; a showdown boss's own death is amplified.
• 10×: a longer slow motion and a flash. The chip explodes into pieces; a showdown boss dies at full intensity.
• 100×: the longest freeze, in which the boss says its last words, then the biggest explosion. A nemesis says its own defeat line instead.
• Reduced motion and the Screen effects setting are respected: reduced motion keeps only the flashes, and with screen effects off there is no shake or flash.

Consumables used mid-fight

• Use a tarot, spectral or planet during a boss fight and the boss answers, naming the card. Tarots and spectrals are grouped by what they do.
• Planets read your hand history: level up your most played hand and the boss mocks the new level; level up a hand you never play and it calls it a waste.
• The Wheel of Fortune reacts to a hit, a miss, or rigged odds (for example with Oops! All 6s).
• The same card gets a line once per turn, quick spam is collapsed, and the line comes after the card's effect has played out.

Jokers created mid-fight

• A joker created during the fight gets one line per blind, naming it.
• Judgement, The Soul, Wraith and Ankh say the joker line instead of their card line.
• Riff-raff's jokers arrive during the intro, so they get no line.

Combo jabs

• About ten famous joker pairs can be called out at the intro, such as Blueprint & Brainstorm or Baron & Mime.

Fixes

• Bosses keep talking after Hieroglyph or Petroglyph send the run back to ante 0 or below.
• Both Spanish translations are rewritten, and the other languages are updated.

For mod authors

• The overkill keys are removed. Use fear_1, fear_2, fear_3 and last_words instead.
• New moments: fear_1..3, last_words, used_tarot_<group>, used_spectral_<group>, used_tarot_wheel_hit, used_tarot_wheel_miss, used_tarot_wheel_rigged, used_planet_main, used_planet_waste, the used_tarot, used_spectral and used_planet fallbacks, joker_created and jab_combo. See the README for the groups.
• Placeholders: #2# now also names the card, the planet's hand, the new joker, or both jokers of a combo ("A & B"); the new #3# is a planet's new hand level.

Developer keys

• The Shift+F6 jab cycle now includes combo.

1.2.0

Savage bosses that read your run.

A new voice

• Every boss line is rewritten: bosses trash-talk now, each in its own personality (bully, smug genius, cold killer, sweet venom, chaos gremlin, royal snob), in all 15 languages.
• Intros are threats, not rule explanations (the game already shows the rule).
• Shorter showdown intros: two lines, the boss's name (or its rematch or nemesis line), then its threat.
• More variety where lines repeat most: three intros, three big-hand reactions and three gloats per boss.
• Swearing is censored ("sh*t") and gets a short TV-style bleep. No slurs, nothing about real people or groups.

Bosses read your run

• Intro jabs: about one intro in three, the boss's threat is replaced by a jab at how you got here: skipped blinds, rerolling the shop, being broke or loaded, a one-suit deck, a tiny or huge deck, no jokers or a full row, a famous joker. Never the same jab twice in a row. Counter jokers are always called out: bosses know your Chicot, Luchador, Matador and Mr. Bones, and every vanilla boss has its own line for its main counter.
• During the fight: comments on weak hands, the same hand three times in a row, burning every discard early and one-card plays. A weak hit now gets a line (final bosses laugh first). Winning with twice the score needed gets an overkill line instead of the defeat line half the time.
• Idle taunts: sit on your hand for 25 seconds and the boss gets impatient (twice per blind at most).
• Regular bosses talk more but never crowd you: at most one line every other hand, and at most one comment on your play per blind. Their last-hand taunt, disabled line and defeat line always come.
• Final bosses make at most three comments on your play per blind, never on two hands in a row.
• The last-hand taunt now comes when you are down to your final hand, before you play it.
• Boss dialogue off silences all of it.

Poke the boss

• Click the boss chip during a boss fight and it jiggles and says something. Click it three times within two seconds for a harsher line. Drag it and it springs back after about a second, even while you hold it, and the boss reacts as it returns.
• Each personality takes it its own way: the bully is furious, the killer goes cold, the royal is offended, the smug genius talks down to you, sweet venom turns poisonous, the chaos gremlin laughs.
• In a showdown, poke the roaming boss avatar. Not during intros, cinematics, menus or pauses, once the winning hand is in, nor before the ante where boss dialogue starts. With Boss dialogue off the boss still reacts, silently.

For mod authors

• register_encounter accepts personality (bully, smug, killer, venom, chaos, royal; default bully): your boss gets that personality's run comments and poke reactions without writing any line.
• Lines now resolve boss, then personality (fb_p_<personality>_<moment>_<n>), then generic. New moments: weak, overkill, idle, jab_*, read_*, poked, poked_hard, grabbed.
• The shared showdown lines fb_opener_<n> and fb_closer_<n> are no longer used; a rematch or nemesis line now replaces the boss's name line.

Developer keys

• Shift+F6 fakes a run state and says the jab it gives (cycles skipped, rerolls, broke, loaded, one suit, counter, famous); Shift+F7 forces an idle taunt.

1.1.0

Boss personality, phases and memory.

Boss moves

• Every vanilla boss performs a visible move the moment its effect hits, with a sound at its own voice pitch. The Hook whips a chain at the two cards it discards, The Tooth bites your played cards and drains your coins, The Arm slams the Raised Fist onto your hand level, The Serpent's snake crawls in with its 3-card refill, The House sweeps the hand as the face-down cards are dealt, and so on for all 28 bosses.
• Card curses now stay on the cards: The Club, Goad, Window and Head put a suit-coloured frame and badge on each cursed card, The Plant and Verdant Leaf grow vines, The Pillar cracks. They go away when the curse does.
• Bosses that change your setup when the blind starts (The Wall, The Water, The Needle, The Manacle, Violet Vessel, Amber Acorn) play their move the moment the blind is set. You see your value go from before to after: the Wall's and the Vessel's target counts up from the normal target, The Needle stabs the hands counter and drops it one hand at a time, The Water washes the discards away, The Manacle chains your hand.
• In showdowns the move comes from the boss avatar; otherwise from the boss chip in the HUD. Bosses from other mods burst when they act.
• New setting: Boss moves (needs Screen effects).

Final bosses

• Each final boss dies its own way: Crimson Heart shatters into hearts, Verdant Leaf blows away in a gust of leaves, Amber Acorn cracks open into shards, Violet Vessel spills purple liquid over the table, Cerulean Bell rings one last time and breaks.
• Phases: at 50% and 25% HP a final boss transforms with a short cinematic (slow motion, a flash, the music dips, its own move erupts), says a phase line and gets a new stance and a II / III marker on its HP bar. The winning hand and your last hand never transform it, and a boss that has been disabled (for example by Chicot) has no phases: it gets angry at 50% and 25% instead and says its disabled line again.
• New setting: Boss phases change the rules (off by default). Each final boss twists its own mechanic in phase II and III: Amber Acorn reshuffles your jokers, Verdant Leaf withers 1 then 2 cards with vines once you have sold a joker, Violet Vessel heals 10% of its requirement per phase (jumping to phase III heals twice), Crimson Heart disables 2 jokers per hand, Cerulean Bell forces 2 cards.

Memory

• Bosses remember you across runs, per Balatro profile: they greet you with a rematch line depending on whether you won or lost last time. Seeded and challenge runs count too.
• Lose three times to the same boss and it becomes your nemesis: a NEMESIS title or tag, a crimson aura, its own intro and defeat lines, and a gold banner when you finally beat it.
• Ten achievements, from Rude! (interrupt a boss) to Twisted (beat all five final bosses with phase twists on). They use Steamodded's achievement system and settings.
• New setting: Boss memory. Turning it off hides the rematch lines and the nemesis presentation; your records keep counting.

For mod authors

• FinalBoss.register_encounter accepts moves (trigger kind to a recipe of effects) and death (a built-in death name or a recipe); new line keys phase2, phase3, rematch_won, rematch_lost, plus the shared fb_nemesis_intro_<n> and fb_nemesis_defeat_<n>.

Developer keys

• Shift+F5 forces the next regular boss, F7 also dumps boss memory, F8 pushes the current final boss to its next phase, F9 makes the current boss your nemesis (for testing; it does not count for Nemesis Slayer).

1.0.0

First release.

Encounters

• Every boss blind talks: an intro line when it starts, reactions to your big hands, close calls and last hand, a line when it is disabled, and a defeat line.
• Showdown bosses get the full treatment: an opener, the boss name, its threat and a closer, and every reaction once per blind.
• Play a hand while the boss is still talking and you interrupt it: it snaps and says its interrupted line instead.
• Lose to a boss and Jimbo mocks you on the game-over screen with that boss's catchphrase.
• Dialogue for all 28 vanilla bosses plus generic lines for modded bosses, in 15 languages.

Showdown stage

• Showdown music: Adam Isiah's orchestral cover of the Balatro main theme plays during showdowns (used with permission).
• Screen effects: vignette, shake, flash and shatter.
• Cinematic intro: letterbox bars, a "SHOWDOWN" title band with the boss name, and the boss avatar falling onto the table.
• Roaming boss avatar with its own HP bar, damage numbers and a white damage trail.
• Living arena: the background takes the boss's colours, pulses on each hand and darkens as the boss gets wounded; the music pitches up in the final stretch.
• The boss reacts when your score lands: it flinches, cracks and trembles as it gets wounded, and laughs off weak hits.
• Explosive finale: the winning hand slows time while the boss cracks and says its last line, then it explodes.
• Game-over gloat: the boss sits beside the game-over panel and laughs at you.

Settings

• Independent toggles for dialogue, music, screen effects and showdown cinematics, plus intro speed and the first ante for regular-boss dialogue.
• Showdown schedule: choose a first ante and an interval to get extra showdowns, with a live ante track.
• Themed config menu in the boss palette, with a Credits tab.
• Respects Balatro's reduced motion setting: colours and flashes stay, movement goes.

For mod authors

• FinalBoss.register_encounter gives your bosses their own tier, voice pitch, music and effects; modded bosses get generic lines with no setup.