From 67ad4900b91aa89cc42eb3206ba6e8eac2205386 Mon Sep 17 00:00:00 2001
From: Jesse Sestito <nobutadas.one@gmail.com>
Date: Sun, 17 May 2026 15:59:43 -0500
Subject: [PATCH] [lua] Add progressOptionalCutscene hook and update
 battlefield

This adds a new hook for dead C++ code to allow for events that start targetable and then turn into untargetable cutscenes.
---
 scripts/globals/battlefield.lua               |  2 +-
 scripts/globals/interaction/actions/event.lua | 11 ++++++++++-
 scripts/globals/interaction/container.lua     |  7 +++++++
 tools/ci/sanity_checks/lua_binding_usage.py   |  2 ++
 4 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/scripts/globals/battlefield.lua b/scripts/globals/battlefield.lua
index 0b8f3280489..a9ffb4481b5 100644
--- a/scripts/globals/battlefield.lua
+++ b/scripts/globals/battlefield.lua
@@ -934,7 +934,7 @@ end
 
 function Battlefield.onExitTrigger(player, npc)
     if player:getBattlefield() then
-        return Battlefield:progressCutscene(32003)
+        return Battlefield:progressOptionalCutscene(32003, { cs_option = 3 })
     end
 end
 
diff --git a/scripts/globals/interaction/actions/event.lua b/scripts/globals/interaction/actions/event.lua
index 2fa48a34f9c..b889cbc1a17 100644
--- a/scripts/globals/interaction/actions/event.lua
+++ b/scripts/globals/interaction/actions/event.lua
@@ -18,13 +18,16 @@ function Event:new(eventId, ...)
     obj.options = { ... }
     obj.priority = Action.Priority.Event -- default priority to 10
     obj.isCutscene = false
+    obj.isOptionalCutscene = false
     return obj
 end
 
 ---@param player CBaseEntity
 ---@param targetEntity CBaseEntity
 function Event:perform(player, targetEntity)
-    if self.isCutscene and player.startCutscene then
+    if self.isOptionalCutscene and player.startOptionalCutscene then
+        player:startOptionalCutscene(self.id, unpack(self.options))
+    elseif self.isCutscene and player.startCutscene then
         player:startCutscene(self.id, unpack(self.options))
     else
         player:startEvent(self.id, unpack(self.options))
@@ -38,3 +41,9 @@ function Event:cutscene()
     self.isCutscene = true
     return self
 end
+
+---@return TEvent
+function Event:optionalCutscene()
+    self.isOptionalCutscene = true
+    return self
+end
diff --git a/scripts/globals/interaction/container.lua b/scripts/globals/interaction/container.lua
index 84aa5fc0dd8..c30448a4951 100644
--- a/scripts/globals/interaction/container.lua
+++ b/scripts/globals/interaction/container.lua
@@ -71,6 +71,13 @@ function Container:progressCutscene(eventid, ...)
     return Event:new(eventid, ...):cutscene():progress()
 end
 
+---@param eventid integer
+---@param ... integer|table
+---@return TEvent
+function Container:progressOptionalCutscene(eventid, ...)
+    return Event:new(eventid, ...):optionalCutscene():progress()
+end
+
 ---@param eventid integer
 ---@param ... integer|table
 ---@return TEvent
diff --git a/tools/ci/sanity_checks/lua_binding_usage.py b/tools/ci/sanity_checks/lua_binding_usage.py
index cc81deff608..17b39f7c547 100644
--- a/tools/ci/sanity_checks/lua_binding_usage.py
+++ b/tools/ci/sanity_checks/lua_binding_usage.py
@@ -39,8 +39,10 @@ def main():
     function_names.append("begin")
     function_names.append("progress")
     function_names.append("cutscene")
+    function_names.append("optionalCutscene")
     function_names.append("progressEvent")
     function_names.append("progressCutscene")
+    function_names.append("progressOptionalCutscene")
     function_names.append("importantOnce")
     function_names.append("perform")
     function_names.append("addNext")