Balatro Feel¶

A card hand with hover lift, drag-to-reorder, and punchy selection juice.

Upstream: https://github.com/mixandjam/balatro-feel

Licence: this port's own code is offered under MIT, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-1

Balatro Feel (SimVX port)¶

SimVX port of mixandjam/balatro-feel, André Cardoso’s Unity study of what makes Balatro’s card hand feel so good. Seven procedurally drawn cards fan across the table; each lifts and tilts toward the cursor on hover, punches when selected, and swaps slots with its neighbours while dragged. Playing a hand pulses the selected cards left to right before clearing them.

There is no scoring and no deck: the whole point is the feel.

Licensing: clean re-implementation under MIT, with every card face, suit pip, and drop shadow generated at runtime as a NumPy array. No upstream art, audio, or code is redistributed. See ATTRIBUTION.md and LICENSE.

Run¶

# from the repo root
uv run python examples/ports/balatro_feel/main.py            # interactive
uv run python examples/ports/balatro_feel/main.py --test     # headless capture (3 frames)
uv run python examples/ports/balatro_feel/harness.py         # scripted-input capture (7 stages)
uv run simvx export web examples/ports/balatro_feel/main.py \
    -o /tmp/balatro_feel.html

Controls¶

Every action has an on-screen button, so mouse or touch alone is enough; the keys are shortcuts for the same verbs.

Input	Action
Hover	Lift, scale-up, parallax tilt toward the cursor
Click	Toggle selection (selected cards rest higher)
Drag	Card follows the cursor; crossing a neighbour swaps their slots
Play hand / Space	Pulse the selected cards left to right, then deselect
Discard / Delete	Remove the hovered card, or every selected card
Clear / right-click	Deselect all
New hand	Re-deal the seven cards
Menu / Esc	Back to the menu (Esc quits from the menu)

What it demonstrates¶

Signals as the seam between logic and juice. Card owns the interaction state and emits a signal per change; CardVisual connects to those signals in its constructor and answers each one with a spring, a punch, or a scale. Neither node calls the other.
Coroutines for animation. Each punch is a damped-sine coroutine started on the event and finishing on its own, with no tween graph or update-flag bookkeeping.
InputMap actions polled from on_update, so one code path serves the window, a touch screen, and the scripted harness.
Procedural textures. nodes/card_textures.py rasterises each face into an RGBA uint8 array (rounded corners, freetype rank glyphs, vector suit pips, soft drop shadow) and hands it straight to Sprite2D. No asset files ship with the port.
z_index draw order, so a hovered, selected, or dragged card lifts above its neighbours while resting cards keep slot order.
Resize-aware layout. The hand centre and every text box are recomputed from the tree’s screen_resized signal; the controls strip is anchored, so the port follows a desktop window resize and the responsive web canvas alike.

Layout¶

balatro_feel/
├── main.py                # entry, InputMap actions, menu + table screens, controls strip
├── harness.py             # scripted input via InputSimulator + staged screenshots
├── nodes/
│   ├── card.py            # Card (state + signals) and CardVisual (spring-follow juice)
│   ├── card_textures.py   # procedural card faces, suit pips, drop shadow
│   └── hand_holder.py     # fan layout, slot swapping, input dispatch, hand verbs
├── screenshots/           # idle + harness captures
├── ATTRIBUTION.md
└── LICENSE

License¶

MIT (matches upstream).

Source files¶

File	Summary	Lines
`main.py`	Balatro Feel: A card hand with hover lift, drag-to-reorder, and punchy selection juice.	291
`harness.py`	Scripted-input harness: exercises the menu, hover, select, drag, and play.	129
`nodes/__init__.py`		0
`nodes/card.py`	Card node: interactive root + smoothly-following visual.	401
`nodes/card_textures.py`	Procedural card-face textures.	333
`nodes/hand_holder.py`	HorizontalHandHolder: owns slots, dispatches input, animates the fan curve.	252

Source¶

"""Balatro Feel: A card hand with hover lift, drag-to-reorder, and punchy selection juice.

# /// simvx
# tags = ["port", "tier-1"]
# upstream = "https://github.com/mixandjam/balatro-feel"
# web = { width = 1280, height = 720, responsive = true }
# ///

Re-implements the mixandjam "Balatro-feel" Unity demo in pure SimVX. Seven procedurally
drawn cards fan across the table; each lifts and tilts toward the cursor on hover, punches
when selected, and swaps slots with its neighbours while dragged. Playing a hand pulses
the selected cards left to right before clearing them.

Demonstrates:
    * A logic node (Card) driving a spring-following visual (CardVisual): events arrive
      as Signals, so the card never has to know a visual exists.
    * Coroutines for damped-sine punch animation: started per event, self-terminating.
    * InputMap actions polled from on_update, so one code path serves the window, a
      touch screen, and the scripted harness.
    * Procedural RGBA NumPy textures handed straight to Sprite2D, with no asset files.
    * z_index draw-order control, so the active card lifts above its neighbours.
    * Engine UI Controls anchored into a resize-aware bottom controls strip.

Controls (every action also has an on-screen button, so mouse or touch alone is enough):
    Move over a card      lift, scale-up, parallax tilt toward the cursor
    Click a card          toggle selection
    Drag a card           reorder the hand; slots swap as it crosses a neighbour
    Right-click / Clear   deselect every card
    Space / Play hand     pulse the selected cards in order, then deselect them
    Delete / Discard      remove the hovered card, or the selected ones
    Esc                   back to the menu (quits from the menu)

Run:
    uv run python examples/ports/balatro_feel/main.py
    uv run python examples/ports/balatro_feel/main.py --test    # headless capture
    uv run simvx export web examples/ports/balatro_feel/main.py -o /tmp/balatro_feel.html
"""

from __future__ import annotations

import sys
from collections.abc import Callable
from pathlib import Path

# Allow running from any cwd
_PORT_DIR = Path(__file__).resolve().parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes.card_textures import make_default_hand  # noqa: E402
from nodes.hand_holder import HorizontalHandHolder  # noqa: E402

from simvx.core import Input, InputMap, Key, MouseButton, Node2D, Text2D, Vec2  # noqa: E402
from simvx.core.ui.containers import HBoxContainer  # noqa: E402
from simvx.core.ui.enums import AnchorPreset  # noqa: E402
from simvx.core.ui.widgets import Button, Panel  # noqa: E402
from simvx.graphics import App  # noqa: E402

WIDTH = 1280
HEIGHT = 720

# Bottom controls strip
STRIP_HEIGHT = 72
BUTTON_W = 148
BUTTON_H = 40
BUTTON_GAP = 12
STRIP_COLOUR = (0.86, 0.86, 0.88, 1.0)
TABLE_COLOUR = (0.06, 0.15, 0.12, 1.0)


class MenuScreen(Node2D):
    """Landing screen: title, house rules, and a Play button reachable by mouse or touch."""

    def __init__(self, on_start: Callable[[], None]) -> None:
        super().__init__(name="Menu")
        self._on_start = on_start

    def on_ready(self) -> None:
        # A non-interactive hand peeks over the bottom edge as a backdrop: same
        # nodes as the table, just never reading input.
        self.backdrop = self.add_child(
            HorizontalHandHolder(
                cards=make_default_hand(),
                centre=Vec2(WIDTH * 0.5, HEIGHT),
                interactive=False,
            )
        )
        self.title = self.add_child(
            Text2D(
                text="Balatro Feel",
                font_scale=3.4,
                align="centre",
                colour=(1.0, 0.94, 0.80, 1.0),
            )
        )
        self.subtitle = self.add_child(
            Text2D(
                text="A SimVX port of the mixandjam card-feel study",
                font_scale=1.2,
                align="centre",
                colour=(0.82, 0.82, 0.88, 1.0),
                fit_to_width=True,
            )
        )
        self.rules = [
            self.add_child(
                Text2D(text=line, font_scale=1.0, align="centre", colour=(0.90, 0.90, 0.93, 1.0), fit_to_width=True)
            )
            for line in (
                "Hover a card to lift it, click to select, drag to reorder the hand.",
                "Play the selected cards for a staged pulse, or discard them outright.",
                "Keys mirror the buttons: Space plays, Delete discards, right-click clears.",
            )
        ]

        self.play_button = Button("Play", on_press=self._on_start)
        self.play_button.font_size = 22.0
        self.play_button.set_anchor_preset(AnchorPreset.CENTER)
        self.play_button.margin_left = -110
        self.play_button.margin_right = 110
        self.play_button.margin_top = 96
        self.play_button.margin_bottom = 150
        self.add_child(self.play_button)

        self._layout(self.tree.screen_size)
        self.tree.screen_resized.connect(self._layout)

    def on_exit_tree(self) -> None:
        self.tree.screen_resized.disconnect(self._layout)

    def _layout(self, size: tuple[float, float]) -> None:
        """Re-centre the copy for the live viewport (desktop resize and responsive web)."""
        w, h = size
        self.title.rect = (0, h * 0.16, w, 60)
        self.subtitle.rect = (0, h * 0.16 + 76, w, 28)
        for idx, line in enumerate(self.rules):
            line.rect = (w * 0.1, h * 0.16 + 132 + idx * 30, w * 0.8, 26)
        self.backdrop.centre = Vec2(w * 0.5, h * 1.02)
        # Anchored Controls resolve their rect from the viewport, which the resize
        # changed without touching any of their own properties: repaint explicitly.
        self.play_button.queue_redraw()


class CardTable(Node2D):
    """The playable hand plus its heading, key hint, and bottom controls strip."""

    def __init__(self, on_menu: Callable[[], None]) -> None:
        super().__init__(name="CardTable")
        self._on_menu = on_menu

    def on_ready(self) -> None:
        self.hand = self.add_child(
            HorizontalHandHolder(
                cards=make_default_hand(),
                centre=Vec2(WIDTH * 0.5, HEIGHT * 0.5),
            )
        )
        self.heading = self.add_child(
            Text2D(
                text="Balatro Feel",
                font_scale=1.6,
                align="centre",
                colour=(1.0, 0.94, 0.80, 1.0),
            )
        )
        self.hint = self.add_child(
            Text2D(
                text="Hover to lift  ·  click to select  ·  drag to reorder  ·  "
                "Space plays  ·  Delete discards  ·  right-click clears",
                font_scale=0.85,
                align="centre",
                colour=(0.75, 0.75, 0.80, 1.0),
                fit_to_width=True,
            )
        )

        self.strip = self.add_child(Panel())
        self.strip.bg_colour = STRIP_COLOUR
        self.strip.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
        self.strip.margin_top = -STRIP_HEIGHT
        self.strip.margin_bottom = 0

        # Buttons live in an HBox so the container owns their positions; the box
        # itself is a top-level Control, anchored bottom-centre with margins.
        self.buttons = self.add_child(HBoxContainer())
        self.buttons.separation = BUTTON_GAP
        self.buttons.alignment = "center"
        actions: tuple[tuple[str, Callable[[], None]], ...] = (
            ("Play hand", self.hand.play_selected),
            ("Discard", self.hand.discard),
            ("Clear", self.hand.clear_selection),
            ("New hand", self._new_hand),
            ("Menu", self._on_menu),
        )
        for label, handler in actions:
            button = Button(label, on_press=handler)
            button.size = (BUTTON_W, BUTTON_H)
            button.font_size = 16.0
            self.buttons.add_child(button)
        total_w = len(actions) * BUTTON_W + (len(actions) - 1) * BUTTON_GAP
        self.buttons.set_anchor_preset(AnchorPreset.CENTER_BOTTOM)
        self.buttons.margin_left = -total_w * 0.5
        self.buttons.margin_right = total_w * 0.5
        self.buttons.margin_top = -(STRIP_HEIGHT + BUTTON_H) * 0.5
        self.buttons.margin_bottom = self.buttons.margin_top + BUTTON_H

        self._layout(self.tree.screen_size)
        self.tree.screen_resized.connect(self._layout)

    def on_exit_tree(self) -> None:
        self.tree.screen_resized.disconnect(self._layout)

    def _new_hand(self) -> None:
        self.hand.deal(make_default_hand())

    def _layout(self, size: tuple[float, float]) -> None:
        """Recompute hand centre and text boxes from the live viewport size."""
        w, h = size
        table_h = max(320.0, h - STRIP_HEIGHT)
        self.hand.centre = Vec2(w * 0.5, table_h * 0.56)
        # Cards are hit-tested by the holder, not by the UI layer, so it needs to
        # know where the strip starts to stop treating strip clicks as card clicks.
        self.hand.input_clip_bottom = h - STRIP_HEIGHT
        self.heading.rect = (0, 34, w, 34)
        self.hint.rect = (w * 0.05, h - STRIP_HEIGHT - 34, w * 0.9, 24)
        # Anchored Controls resolve their rect from the viewport, which the resize
        # changed without touching any of their own properties: repaint explicitly.
        for control in (self.strip, self.buttons, *self.buttons.children):
            control.queue_redraw()


class BalatroFeelRoot(Node2D):
    """Root scene: swaps between the menu and the card table."""

    def on_ready(self) -> None:
        # Input actions belong to the root's ready path: the web export never calls main().
        InputMap.add_action("primary", [MouseButton.LEFT])
        InputMap.add_action("clear_selection", [MouseButton.RIGHT])
        InputMap.add_action("play_hand", [Key.SPACE])
        InputMap.add_action("discard_card", [Key.DELETE])
        InputMap.add_action("back", [Key.ESCAPE])

        self.screen: Node2D | None = None
        self.show_menu()

    def _swap_screen(self, screen: Node2D) -> None:
        if self.screen is not None:
            self.remove_child(self.screen)
        self.screen = self.add_child(screen)

    def show_menu(self) -> None:
        self._swap_screen(MenuScreen(on_start=self.show_table))

    def show_table(self) -> None:
        self._swap_screen(CardTable(on_menu=self.show_menu))

    def on_update(self, dt: float) -> None:
        if Input.is_action_just_pressed("back"):
            if isinstance(self.screen, CardTable):
                self.show_menu()
            else:
                self.app.quit()

    def on_draw(self, renderer) -> None:
        # Felt backdrop behind every screen. Oversized so a resized window stays
        # covered without redrawing; the colour never changes, so one capture is enough.
        renderer.draw_rect((0, 0), (WIDTH * 4, HEIGHT * 4), colour=TABLE_COLOUR, filled=True)


def main() -> None:
    headless = "--test" in sys.argv
    if headless:
        from simvx.graphics import save_png

        capture_at = [30, 60, 119]
        app = App(width=WIDTH, height=HEIGHT, title="Balatro Feel (SimVX)", visible=False)
        frames = app.run_headless(BalatroFeelRoot(), frames=120, capture_frames=capture_at)
        out_dir = _PORT_DIR / "screenshots"
        out_dir.mkdir(exist_ok=True)
        for idx, img in zip(capture_at, frames, strict=False):
            out_path = out_dir / f"frame_{idx}.png"
            save_png(img, out_path)
            print(f"saved {out_path}")
        app.quit()
    else:
        app = App(width=WIDTH, height=HEIGHT, title="Balatro Feel (SimVX)")
        app.run(BalatroFeelRoot())


if __name__ == "__main__":
    main()