feat: add fps cap setting

Author: S1M0N38

docs/cli.md

@@ -24,6 +24,7 @@ All options can be set via CLI flags or environment variables. CLI flags overrid
 | `--audio`                     | `BALATROBOT_AUDIO`         | `0`           | Enable audio                               |
 | `--debug`                     | `BALATROBOT_DEBUG`         | `0`           | Enable debug mode (requires DebugPlus mod) |
 | `--no-shaders`                | `BALATROBOT_NO_SHADERS`    | `0`           | Disable all shaders                        |
+| `--fps-cap FPS_CAP`           | `BALATROBOT_FPS_CAP`       | `60`          | Maximum FPS cap                            |
 | `--balatro-path BALATRO_PATH` | `BALATROBOT_BALATRO_PATH`  | auto-detected | Path to Balatro game directory             |
 | `--lovely-path LOVELY_PATH`   | `BALATROBOT_LOVELY_PATH`   | auto-detected | Path to lovely library (dll/so/dylib)      |
 | `--love-path LOVE_PATH`       | `BALATROBOT_LOVE_PATH`     | auto-detected | Path to LOVE executable (native only)      |

src/balatrobot/cli.py

@@ -15,6 +15,7 @@ def create_parser() -> argparse.ArgumentParser:
     # No defaults - env vars and dataclass defaults handle it
     parser.add_argument("--host", help="Server hostname (default: 127.0.0.1)")
     parser.add_argument("--port", type=int, help="Server port (default: 12346)")
+    parser.add_argument("--fps-cap", type=int, help="Maximum FPS cap (default: 60)")
     parser.add_argument("--logs-path", help="Directory for log files (default: logs)")
 
     # Boolean flags - store_const so None means "not provided" -> check env var

src/balatrobot/config.py

@@ -14,6 +14,7 @@
     "audio": "BALATROBOT_AUDIO",
     "debug": "BALATROBOT_DEBUG",
     "no_shaders": "BALATROBOT_NO_SHADERS",
+    "fps_cap": "BALATROBOT_FPS_CAP",
     "balatro_path": "BALATROBOT_BALATRO_PATH",
     "lovely_path": "BALATROBOT_LOVELY_PATH",
     "love_path": "BALATROBOT_LOVE_PATH",
@@ -24,7 +25,7 @@
 BOOL_FIELDS = frozenset(
     {"fast", "headless", "render_on_api", "audio", "debug", "no_shaders"}
 )
-INT_FIELDS = frozenset({"port"})
+INT_FIELDS = frozenset({"port", "fps_cap"})
 
 
 def _parse_env_value(field: str, value: str) -> str | int | bool:
@@ -51,6 +52,7 @@ class Config:
     audio: bool = False
     debug: bool = False
     no_shaders: bool = False
+    fps_cap: int = 60
 
     # Launcher
     balatro_path: str | None = None

src/lua/settings.lua

@@ -24,6 +24,9 @@ BalatroBot configure settings in Balatro using the following environment variabl
 
   - BALATROBOT_NO_SHADERS: whether to disable all shaders for better performance.
       1 for disable shaders, 0 for enable shaders (default: 0)
+
+  - BALATROBOT_FPS_CAP: the maximum FPS cap for the game.
+      Type number (default: 60)
 ]]
 
 ---@diagnostic disable: duplicate-set-field
@@ -38,6 +41,7 @@ BB_SETTINGS = {
   audio = os.getenv("BALATROBOT_AUDIO") == "1" or false,
   debug = os.getenv("BALATROBOT_DEBUG") == "1" or false,
   no_shaders = os.getenv("BALATROBOT_NO_SHADERS") == "1" or false,
+  fps_cap = tonumber(os.getenv("BALATROBOT_FPS_CAP")) or 60,
 }
 
 ---@type boolean?
@@ -67,7 +71,7 @@ local function configure_settings()
   G.F_MUTE = true
 
   -- performance
-  G.FPS_CAP = 60
+  G.FPS_CAP = BB_SETTINGS.fps_cap
   G.SETTINGS.GAMESPEED = 4
   G.ANIMATION_FPS = 10
 

src/lua/utils/types.lua

@@ -275,6 +275,7 @@
 ---@field audio boolean Whether to play audio (enables sound thread and sets volume levels)
 ---@field debug boolean Whether debug mode is enabled (requires DebugPlus mod)
 ---@field no_shaders boolean Whether to disable all shaders for better performance (causes visual glitches)
+---@field fps_cap integer Maximum FPS cap for the game (default: 60)
 ---@field setup fun()? Initialize and apply all BalatroBot settings
 
 ---@class Debug