From 8cf5e343d881e00463e2581bd9932e7feaf3f427 Mon Sep 17 00:00:00 2001
From: Eric Lewis <ericlewis777@gmail.com>
Date: Tue, 11 Aug 2026 04:21:40 -0400
Subject: [PATCH 1/4] Add Noble.performTransition() to play a transition
 without changing scenes. (upstream issue #82)

Implements upstream issue #82. Noble.performTransition(__duration,
__transition, __transitionProperties) plays a transition animation while
the current scene stays loaded and active: the scene's exit(), finish(),
enter(), and start() methods are not called, and no new scene is created.
User input is disabled when the transition starts and the current scene's
inputHandler is restored when it completes, without re-running start().

Transitions now also accept per-invocation callback properties (onStart,
onMidpoint, onHoldTimeElapsed, onComplete) in the transition properties
table, which shadow the transition's callback methods for that invocation
only. This enables the headline use case: dip to black, mutate the current
scene at the midpoint while the screen is obscured, then dip back.

Existing Noble.transition() behavior is unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .docs/modules/Noble.html     | 54 +++++++++++++++++++++++++++++++++
 Noble.lua                    | 58 ++++++++++++++++++++++++++++++++++--
 modules/Noble.Transition.lua | 15 ++++++++++
 3 files changed, 125 insertions(+), 2 deletions(-)

diff --git a/.docs/modules/Noble.html b/.docs/modules/Noble.html
index 06d3394..892d5c8 100644
--- a/.docs/modules/Noble.html
+++ b/.docs/modules/Noble.html
@@ -304,6 +304,7 @@ <h3>Parameters</h3>
 
 							<h3>See</h3>
 							<ul>
+									<li><a href="../modules/Noble.html#performTransition">Noble.performTransition</a></li>
 									<li><a href="../modules/Noble.html#isTransitioning">Noble.isTransitioning</a></li>
 									<li><a href="../classes/NobleScene.html#">NobleScene</a></li>
 									<li><a href="../modules/Noble.Transition.html#">Noble.Transition</a></li>
@@ -336,6 +337,59 @@ <h3>Usage</h3>
 	}
 )</pre>
 
+					</dd>
+					<dt>
+						<a name = "performTransition"></a>
+						<span class="item-name">performTransition([__duration=1.5[, __transition=Noble.Transition.DipToBlack[, __transitionProperties={}]]])<span>
+					</dt>
+					<dd>
+						Play a transition animation without changing scenes (at the end of this frame).
+ The current scene stays loaded and remains the active scene, but user input is disabled until the transition completes. To run code at specific moments during the transition, use the transition's callback properties, such as <code>onMidpoint</code> and <code>onComplete</code>.
+ Additional calls to this method (or to <code>Noble.transition</code>) within the same frame (before the already-called transition begins), will override previous calls. Any calls to this method once a transition begins will be ignored until the transition completes.
+
+								<h3>Parameters</h3>
+							<ul class="parameters">
+													<li><span class="parameter">__duration</span>
+															<span class="types"><span class="type">number</span></span>
+															<span class="default">= <span class="value">1.5</span> (default)</span>
+														<br/>
+														 The length of the transition, in seconds.
+													</li>
+													<li><span class="parameter">__transition</span>
+															<span class="types"><span class="type">Noble.Transition</span></span>
+															<span class="default">= <span class="value">Noble.Transition.DipToBlack</span> (default)</span>
+														<br/>
+														 If a transition duration is set, use this transition type. If not set, it will use the value of <code>configuration.defaultTransition</code>.
+													</li>
+													<li><span class="parameter">__transitionProperties</span>
+															<span class="types"><span class="type">table</span></span>
+															<span class="default">= <span class="value">{}</span> (default)</span>
+														<br/>
+														 A table consisting of properties for this transition. Properties not set here will use values that transition's <code>defaultProperties</code> table.
+													</li>
+							</ul>
+
+
+
+							<h3>See</h3>
+							<ul>
+									<li><a href="../modules/Noble.html#transition">Noble.transition</a></li>
+									<li><a href="../modules/Noble.html#isTransitioning">Noble.isTransitioning</a></li>
+									<li><a href="../modules/Noble.Transition.html#">Noble.Transition</a></li>
+							</ul>
+
+							<h3>Usage</h3>
+								<pre class="example">Noble.<span class="function-name">performTransition</span>(<span class="number">1.5</span>, Noble.Transition.DipToBlack,
+	{
+		holdTime = <span class="number">0.5</span>,
+		onMidpoint = <span class="keyword">function</span>()
+			<span class="comment">-- The screen is fully obscured, so we can modify the
+</span>			<span class="comment">-- current scene without the player seeing it happen.
+</span>			player:moveTo(<span class="number">50</span>, <span class="number">100</span>)
+		<span class="keyword">end</span>
+	}
+)</pre>
+
 					</dd>
 					<dt>
 						<a name = "currentScene"></a>
diff --git a/Noble.lua b/Noble.lua
index 9f69600..5366f10 100644
--- a/Noble.lua
+++ b/Noble.lua
@@ -203,6 +203,7 @@ end
 --
 local currentTransition = nil
 local queuedScene = nil
+local transitionIsSceneless = false
 
 --- Transition to a new scene (at the end of this frame).
 --- This method will create a new scene, mark the previous one for garbage collection, and animate between them.
@@ -238,6 +239,7 @@ local queuedScene = nil
 -- 		levelData = "levels/level2.json",
 -- 	}
 -- )
+-- @see Noble.performTransition
 -- @see Noble.isTransitioning
 -- @see NobleScene
 -- @see Noble.Transition
@@ -254,6 +256,47 @@ function Noble.transition(NewScene, __duration, __transition, __transitionProper
 
 	local sceneProperties = __sceneProperties or {}
 	queuedScene = NewScene(sceneProperties) -- Creates new scene object. Its init() function runs now.
+	transitionIsSceneless = false
+
+	currentTransition = (__transition or configuration.defaultTransition)(
+		__duration or configuration.defaultTransitionDuration,
+		__transitionProperties or {}
+	)
+end
+
+--- Play a transition animation without changing scenes (at the end of this frame).
+--- The current scene stays loaded and remains the active scene, but user input is disabled until the transition completes. To run code at specific moments during the transition, use the transition's callback properties, such as `onMidpoint` and `onComplete`.
+--- Additional calls to this method (or to `Noble.transition`) within the same frame (before the already-called transition begins), will override previous calls. Any calls to this method once a transition begins will be ignored until the transition completes.
+-- @number[opt=1.5] __duration The length of the transition, in seconds.
+-- @tparam[opt=Noble.Transition.DipToBlack] Noble.Transition __transition If a transition duration is set, use this transition type. If not set, it will use the value of `configuration.defaultTransition`.
+-- @tparam[opt={}] table __transitionProperties A table consisting of properties for this transition. Properties not set here will use values that transition's `defaultProperties` table.
+-- @usage
+-- Noble.performTransition(1.5, Noble.Transition.DipToBlack,
+-- 	{
+-- 		holdTime = 0.5,
+-- 		onMidpoint = function()
+-- 			-- The screen is fully obscured, so we can modify the
+-- 			-- current scene without the player seeing it happen.
+-- 			player:moveTo(50, 100)
+-- 		end
+-- 	}
+-- )
+-- @see Noble.transition
+-- @see Noble.isTransitioning
+-- @see Noble.Transition
+function Noble.performTransition(__duration, __transition, __transitionProperties)
+	if (isTransitioning) then
+		-- This bonk no longer throws an error (compared to previous versions of Noble Engine), but maybe it still should?
+		warn("BONK: You can't start a transition in the middle of another transition, silly!")
+		return -- Let's get otta here!
+	elseif (currentTransition ~= nil) then
+		-- Calling this method multiple times between Noble.update() calls is probably not intentional behavior.
+		warn("Soft-BONK: You are queueing multiple transitions within the same frame. Did you mean to do that?")
+		-- We don't return here because maybe the developer *did* intend to override a previous call.
+	end
+
+	queuedScene = nil					-- Discards any scene queued by a same-frame call to Noble.transition().
+	transitionIsSceneless = true
 
 	currentTransition = (__transition or configuration.defaultTransition)(
 		__duration or configuration.defaultTransitionDuration,
@@ -266,13 +309,16 @@ end
 
 function Noble.transitionStartHandler()
 	isTransitioning = true
-	if (currentScene ~= nil) then
+	if (not transitionIsSceneless and currentScene ~= nil) then
 		currentScene:exit()				-- The current scene runs its "goodbye" code. Sprites are taken out of the simulation.
 	end
 	Noble.Input.setHandler(nil)			-- Disable user input.
 end
 
 function Noble.transitionMidpointHandler()
+	if (transitionIsSceneless) then
+		return							-- The current scene isn't going anywhere. Carry on!
+	end
 	if (currentScene ~= nil) then
 		currentScene:finish()
 		currentScene = nil				-- Allows current scene to be garbage collected.
@@ -285,7 +331,15 @@ end
 function Noble.transitionCompleteHandler()
 	isTransitioning = false				-- Reset
 	currentTransition = nil				-- Clear the transition variable.
-	currentScene:start()				-- The new scene is now active.
+	if (transitionIsSceneless) then
+		transitionIsSceneless = false	-- Reset
+		if (currentScene ~= nil) then
+			Noble.Input.setHandler(currentScene.inputHandler)	-- Re-enable user input, without re-running the current scene's start() code.
+		end
+		Graphics.sprite.redrawBackground()
+	else
+		currentScene:start()			-- The new scene is now active.
+	end
 end
 
 --- Get the current scene object
diff --git a/modules/Noble.Transition.lua b/modules/Noble.Transition.lua
index d51b574..8ba4d23 100644
--- a/modules/Noble.Transition.lua
+++ b/modules/Noble.Transition.lua
@@ -95,6 +95,13 @@ function Noble.Transition:init(__duration, __arguments)
 
 	end
 
+	-- Callback properties for this invocation of this transition. When set, these
+	-- shadow the transition's own callback methods (they do not overwrite them).
+	if (__arguments.onStart ~= nil)				then self.onStart = __arguments.onStart end
+	if (__arguments.onMidpoint ~= nil)			then self.onMidpoint = __arguments.onMidpoint end
+	if (__arguments.onHoldTimeElapsed ~= nil)	then self.onHoldTimeElapsed = __arguments.onHoldTimeElapsed end
+	if (__arguments.onComplete ~= nil)			then self.onComplete = __arguments.onComplete end
+
 	self:setProperties(__arguments)
 
 end
@@ -185,15 +192,23 @@ end
 function Noble.Transition:setProperties(__arguments) end
 
 --- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition starts. Default transitions in Noble Engine do not use this.
+-- You may also set this as a property (`onStart`) when invoking a transition, in order to run custom code for that invocation only. Callbacks set this way receive the transition object as their first argument.
+-- @see Noble.performTransition
 function Noble.Transition:onStart() end
 
 --- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition reaches its midpoint. Default transitions in Noble Engine do not use this.
+-- You may also set this as a property (`onMidpoint`) when invoking a transition, in order to run custom code for that invocation only. Callbacks set this way receive the transition object as their first argument.
+-- @see Noble.performTransition
 function Noble.Transition:onMidpoint() end
 
 --- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition's hold time has elapsed. Default transitions in Noble Engine do not use this.
+-- You may also set this as a property (`onHoldTimeElapsed`) when invoking a transition, in order to run custom code for that invocation only. Callbacks set this way receive the transition object as their first argument.
+-- @see Noble.performTransition
 function Noble.Transition:onHoldTimeElapsed() end
 
 --- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition completes. Default transitions in Noble Engine do not use this.
+-- You may also set this as a property (`onComplete`) when invoking a transition, in order to run custom code for that invocation only. Callbacks set this way receive the transition object as their first argument.
+-- @see Noble.performTransition
 function Noble.Transition:onComplete() end
 
 --- *Do not call this directly.* Implement this in a custom transition to draw the transition. This runs once per frame while the transition is running. See existing transitions for implementation examples.

From 8131352c4c73c5e4d55c42422a02070dc5e0cde6 Mon Sep 17 00:00:00 2001
From: Eric Lewis <ericlewis777@gmail.com>
Date: Tue, 11 Aug 2026 04:41:44 -0400
Subject: [PATCH 2/4] Restore the previously active inputHandler after a
 sceneless transition.

Noble.performTransition() completed by setting the input handler to
currentScene.inputHandler, discarding whatever handler was actually
active when the transition started. Games that manage input separately
from the scene (a documented Noble.Input use-case, e.g. a modal menu
handler set via Noble.Input.setHandler()) would silently lose their
active handler; since NobleScene.inputHandler defaults to an empty
table, all input appeared to stop working. It also re-enabled input
that had been deliberately disabled via Noble.Input.setEnabled(false).

Capture the active handler in Noble.transitionStartHandler() and
restore exactly that in Noble.transitionCompleteHandler(), matching
the documented contract that the current scene "stays loaded and
remains the active scene."

Refs upstream issue #82.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 Noble.lua | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Noble.lua b/Noble.lua
index 5366f10..b48d61c 100644
--- a/Noble.lua
+++ b/Noble.lua
@@ -204,6 +204,7 @@ end
 local currentTransition = nil
 local queuedScene = nil
 local transitionIsSceneless = false
+local scenelessTransitionInputHandler = nil
 
 --- Transition to a new scene (at the end of this frame).
 --- This method will create a new scene, mark the previous one for garbage collection, and animate between them.
@@ -309,7 +310,9 @@ end
 
 function Noble.transitionStartHandler()
 	isTransitioning = true
-	if (not transitionIsSceneless and currentScene ~= nil) then
+	if (transitionIsSceneless) then
+		scenelessTransitionInputHandler = Noble.Input.getHandler()	-- Capture the active inputHandler (which may not be the current scene's) so it can be restored when the transition completes.
+	elseif (currentScene ~= nil) then
 		currentScene:exit()				-- The current scene runs its "goodbye" code. Sprites are taken out of the simulation.
 	end
 	Noble.Input.setHandler(nil)			-- Disable user input.
@@ -333,9 +336,8 @@ function Noble.transitionCompleteHandler()
 	currentTransition = nil				-- Clear the transition variable.
 	if (transitionIsSceneless) then
 		transitionIsSceneless = false	-- Reset
-		if (currentScene ~= nil) then
-			Noble.Input.setHandler(currentScene.inputHandler)	-- Re-enable user input, without re-running the current scene's start() code.
-		end
+		Noble.Input.setHandler(scenelessTransitionInputHandler)	-- Restore the inputHandler that was active when the transition started, without re-running the current scene's start() code.
+		scenelessTransitionInputHandler = nil
 		Graphics.sprite.redrawBackground()
 	else
 		currentScene:start()			-- The new scene is now active.

From 5b4cbf2bc6f343742644a5882533abf5f272a240 Mon Sep 17 00:00:00 2001
From: Eric Lewis <ericlewis777@gmail.com>
Date: Tue, 11 Aug 2026 04:42:52 -0400
Subject: [PATCH 3/4] Run the engine's transition-complete handler before a
 transition's onComplete().

The onComplete closure in Noble.Transition:execute() ran the
transition's onComplete() callback before Noble.transitionCompleteHandler(),
so isTransitioning was still true inside user code. With the new
per-invocation callback properties added in 50be77b, chaining a
transition from onComplete - the natural use of that feature - hit the
"You can't start a transition in the middle of another transition"
guard and was silently dropped. Call the engine handler first, matching
the ordering already used by the onStart and onMidpoint closures, so
the transition state is fully cleared when user code runs.

Refs upstream issue #82.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 modules/Noble.Transition.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/Noble.Transition.lua b/modules/Noble.Transition.lua
index 8ba4d23..bdecc20 100644
--- a/modules/Noble.Transition.lua
+++ b/modules/Noble.Transition.lua
@@ -142,8 +142,8 @@ function Noble.Transition:execute()
 	end
 
 	local onComplete = function()
-		self:onComplete()				-- If this transition has any custom code to run here, run it.
 		Noble.transitionCompleteHandler()
+		self:onComplete()				-- If this transition has any custom code to run here, run it. This runs after the engine's handler (matching onStart/onMidpoint), so a new transition may be started from within this callback.
 	end
 
 	local type = self._type

From ed251de95817b4e415a02870661e415895d073ca Mon Sep 17 00:00:00 2001
From: Eric Lewis <ericlewis777@gmail.com>
Date: Tue, 11 Aug 2026 05:59:11 -0400
Subject: [PATCH 4/4] Add the missing sidebar index entry for
 Noble.performTransition in the generated docs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .docs/modules/Noble.html | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.docs/modules/Noble.html b/.docs/modules/Noble.html
index 892d5c8..c709689 100644
--- a/.docs/modules/Noble.html
+++ b/.docs/modules/Noble.html
@@ -31,6 +31,7 @@ <h3>Functions</h3>
 							<li><a href="#setConfig">.setConfig</a></li>
 							<li><a href="#resetConfig">.resetConfig</a></li>
 							<li><a href="#transition">.transition</a></li>
+							<li><a href="#performTransition">.performTransition</a></li>
 							<li><a href="#currentScene">.currentScene</a></li>
 							<li><a href="#currentSceneName">.currentSceneName</a></li>
 							<li><a href="#isTransitioning">.isTransitioning</a></li>