feat: Add gamestate command for save/load functionality

[S1M0N38]

Summary

Adds a new gamestate console command that provides convenient save state management during gameplay. This allows players to save snapshots of their run at any point and load them back later, which is invaluable for debugging, testing specific scenarios, and experimenting with game mechanics.

Motivation

When debugging or developing mods, it's often necessary to test specific game states repeatedly. Previously, this required either:

• Playing through the entire run to reach the desired state each time
• Manually managing .jkr save files in the file system

This feature streamlines the workflow by providing an in-game interface for save state management.

Usage

Save a Game State

gamestate save <name>

Saves the current game state to <name>.jkr in your profile directory.

Example:

gamestate save after_boss1
gamestate save pre_final_boss
gamestate save interesting_seed

Restrictions:

• Can only save during an active run (not in menus)
• Cannot save while opening booster packs

Load a Game State

gamestate load <name>

Loads a previously saved game state from <name>.jkr.

Example:

gamestate load after_boss1

Note: This will delete your current run and replace it with the loaded state.

List Available Game States

gamestate list

Displays all available .jkr files in your profile directory with their full paths.

Example output:

Available game states:
after_boss1: /Users/player/Library/Application Support/Balatro/1/after_boss1.jkr
pre_final_boss: /Users/player/Library/Application Support/Balatro/1/pre_final_boss.jkr

Technical Details

Implementation

• Core functions (debugplus/core.lua):

  • saveGameState(filename) - Uses Balatro's native save_run() and compress_and_save() functions
  • loadGameState(filename) - Uses get_compressed() and G:start_run() to restore state
  • listGameStates() - Scans profile directory for .jkr files

• Console command (debugplus/console.lua):

  • Input validation (alphanumeric, dash, underscore only)
  • User-friendly error messages
  • Displays absolute paths for saved/loaded files

Path Handling

The implementation supports two path modes:

1. Simple filenames (e.g., save1) - Stored in profile directory
2. Relative paths (e.g., Mods/MyMod/fixtures/test) - Allows mods to bundle test fixtures

File Format

Uses Balatro's native .jkr format (compressed save files), ensuring full compatibility with:

• Manual save file management
• Game's built-in save/load system
• Future game updates

Testing

To test this feature:

1. Start a run in Balatro
2. Open the console (press /)
3. Save your current state: gamestate save test1
4. Make some changes (play a few hands, buy something)
5. Load your saved state: gamestate load test1
6. Verify you're back to the saved state
7. List all states: gamestate list

Notes

• Game state names can only contain letters, numbers, dashes, and underscores
• The command provides clear error messages for invalid operations
• Absolute file paths are shown in success messages for easy file system access

[kasimeka]

ai pr with no linked issue or feature request :(

[S1M0N38]

ai pr with no linked issue or feature request :(

Yeah, the description for this PR was generated by AI but from hand-written code.

I wasn't able to find CONTRIBUTING.md outlining the contribution steps.

I've just PR a feature that I'm using on my fork. Feel free to close it without additional comment if it's not planned.

[WilsontheWolf]

Thanks for the PR. I'm not quite sure the use case for this over the x and z keybinds. I find I almost never used more than 3 keybinds personally. I guess the mod bundled states may be useful for testing stuff, but smods and other mods love breaking stuff with old saves, and the fact that the card's ability table is stored means if you adjust any values your save is just invalid. If you are wanting a system to reliably make game states to make sure things work well, https://github.com/BakersDozenBagels/Balatest/ is probably what you're looking for.