feat: add render on api env var / flag

Author: S1M0N38

balatro.sh

@@ -7,6 +7,7 @@ declare -a FAILED_PORTS=()
 HEADLESS=false
 FAST=false
 AUDIO=false
+RENDER_ON_API=false
 FORCE_KILL=true
 KILL_ONLY=false
 STATUS_ONLY=false
@@ -35,21 +36,24 @@ Usage: $0 [OPTIONS]
        $0 --status
 
 Options:
-  -p, --port PORT  Specify port for Balatro instance (can be used multiple times)
-                   Default: 12346 if no port specified
-  --headless       Enable headless mode (sets BALATROBOT_HEADLESS=1)
-  --fast           Enable fast mode (sets BALATROBOT_FAST=1)
-  --audio          Enable audio (disabled by default, sets BALATROBOT_AUDIO=1)
-  --kill           Kill all running Balatro instances and exit
-  --status         Show information about running Balatro instances
-  -h, --help       Show this help message
+  -p, --port PORT    Specify port for Balatro instance (can be used multiple times)
+                     Default: 12346 if no port specified
+  --headless         Enable headless mode (sets BALATROBOT_HEADLESS=1)
+  --fast             Enable fast mode (sets BALATROBOT_FAST=1)
+  --audio            Enable audio (disabled by default, sets BALATROBOT_AUDIO=1)
+  --render-on-api    Enable on-demand rendering - draws frame only on API calls
+                     Incompatible with --headless
+  --kill             Kill all running Balatro instances and exit
+  --status           Show information about running Balatro instances
+  -h, --help         Show this help message
 
 Examples:
   $0                            # Start single instance on default port 12346
   $0 -p 12347                   # Start single instance on port 12347
   $0 -p 12346 -p 12347          # Start two instances on ports 12346 and 12347
   $0 --headless --fast          # Start with headless and fast mode on default port
   $0 --audio                    # Start with audio enabled on default port
+  $0 --render-on-api            # Start with on-demand rendering on default port
   $0 --kill                     # Kill all running Balatro instances
   $0 --status                   # Show running instances
 
@@ -84,6 +88,10 @@ parse_arguments() {
 			AUDIO=true
 			shift
 			;;
+		--render-on-api)
+			RENDER_ON_API=true
+			shift
+			;;
 		--kill)
 			KILL_ONLY=true
 			shift
@@ -134,6 +142,15 @@ parse_arguments() {
 		fi
 	done
 	PORTS=("${unique_ports[@]}")
+
+	# Validate mutually exclusive options
+	if [[ "$RENDER_ON_API" == "true" ]] && [[ "$HEADLESS" == "true" ]]; then
+		echo "Error: --render-on-api and --headless are mutually exclusive" >&2
+		echo "Choose one rendering mode:" >&2
+		echo "  --headless        No rendering at all (most efficient)" >&2
+		echo "  --render-on-api   Render only on API calls" >&2
+		exit 1
+	fi
 }
 
 # Check if a port is available
@@ -252,6 +269,9 @@ start_balatro_instance() {
 	if [[ "$AUDIO" == "true" ]]; then
 		export BALATROBOT_AUDIO=1
 	fi
+	if [[ "$RENDER_ON_API" == "true" ]]; then
+		export BALATROBOT_RENDER_ON_API=1
+	fi
 
 	# Set up platform-specific Balatro configuration
 	# Platform-specific launch

balatrobot.lua

@@ -4,13 +4,14 @@ assert(SMODS.load_file("src/lua/api.lua"))()
 assert(SMODS.load_file("src/lua/log.lua"))()
 assert(SMODS.load_file("src/lua/settings.lua"))()
 
--- Initialize API
+-- Apply all configuration and Love2D patches FIRST
+-- This must run before API.init() to set G.BALATROBOT_PORT
+SETTINGS.setup()
+
+-- Initialize API (depends on G.BALATROBOT_PORT being set)
 API.init()
 
 -- Initialize Logger
 LOG.init()
 
--- Apply all configuration and Love2D patches
-SETTINGS.setup()
-
 sendInfoMessage("BalatroBot loaded - version " .. SMODS.current_mod.version, "BALATROBOT")

src/lua/api.lua

@@ -150,6 +150,10 @@ function API.update(_)
           )
         else
           sendDebugMessage(data.name .. "(" .. json.encode(args) .. ")", "API")
+          -- Trigger frame render if render-on-API mode is enabled
+          if G.BALATROBOT_SHOULD_RENDER ~= nil then
+            G.BALATROBOT_SHOULD_RENDER = true
+          end
           func(args)
         end
       end

src/lua/settings.lua

@@ -2,6 +2,7 @@
 local headless = os.getenv("BALATROBOT_HEADLESS") == "1"
 local fast = os.getenv("BALATROBOT_FAST") == "1"
 local audio = os.getenv("BALATROBOT_AUDIO") == "1"
+local render_on_api = os.getenv("BALATROBOT_RENDER_ON_API") == "1"
 local port = os.getenv("BALATROBOT_PORT")
 local host = os.getenv("BALATROBOT_HOST")
 
@@ -13,6 +14,7 @@ local config = {
   headless = headless,
   fast = fast,
   audio = audio,
+  render_on_api = render_on_api,
 }
 
 -- Apply Love2D patches for performance
@@ -182,8 +184,52 @@ local function configure_headless()
   sendInfoMessage("BalatroBot: Headless mode enabled - graphics rendering disabled")
 end
 
+-- Configure on-demand rendering (render only when API calls are made)
+local function configure_render_on_api()
+  if not config.render_on_api then
+    return
+  end
+
+  -- Global flag to trigger rendering
+  G.BALATROBOT_SHOULD_RENDER = false
+
+  -- Store original rendering functions
+  local original_draw = love.draw
+  local original_present = love.graphics.present
+  local did_render_this_frame = false
+
+  -- Replace love.draw to only render when flag is set
+  ---@diagnostic disable-next-line: duplicate-set-field
+  love.draw = function()
+    if G.BALATROBOT_SHOULD_RENDER then
+      original_draw()
+      did_render_this_frame = true
+      G.BALATROBOT_SHOULD_RENDER = false
+    else
+      did_render_this_frame = false
+    end
+  end
+
+  -- Replace love.graphics.present to only present when rendering happened
+  ---@diagnostic disable-next-line: duplicate-set-field
+  love.graphics.present = function()
+    if did_render_this_frame then
+      original_present()
+      did_render_this_frame = false
+    end
+  end
+
+  sendInfoMessage("BalatroBot: Render-on-API mode enabled - frames only on API calls")
+end
+
 -- Main setup function
 SETTINGS.setup = function()
+  -- Validate mutually exclusive options
+  if config.headless and config.render_on_api then
+    sendErrorMessage("--headless and --render-on-api are mutually exclusive. Choose one rendering mode.", "SETTINGS")
+    error("Configuration error: mutually exclusive rendering modes specified")
+  end
+
   G.BALATROBOT_PORT = port or "12346"
   G.BALATROBOT_HOST = host or "127.0.0.1"
 
@@ -195,4 +241,7 @@ SETTINGS.setup = function()
 
   -- Apply headless optimizations if needed
   configure_headless()
+
+  -- Apply render-on-API optimizations if needed
+  configure_render_on_api()
 end