Skip to content

Add Noble.performTransition() to play a transition without changing scenes #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ericlewis wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add Noble.performTransition() to play a transition without changing scenes #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8cf5e34
Add Noble.performTransition() to play a transition without changing s…
ericlewis Aug 11, 2026
8131352
Restore the previously active inputHandler after a sceneless transition.
ericlewis Aug 11, 2026
5b4cbf2
Run the engine's transition-complete handler before a transition's on…
ericlewis Aug 11, 2026
ed251de
Add the missing sidebar index entry for Noble.performTransition in th…
ericlewis Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .docs/modules/Noble.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -304,6 +305,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>
Expand Down Expand Up @@ -336,6 +338,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>
Expand Down
60 changes: 58 additions & 2 deletions Noble.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,8 @@ 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.
Expand Down Expand Up @@ -238,6 +240,7 @@ local queuedScene = nil
-- levelData = "levels/level2.json",
-- }
-- )
-- @see Noble.performTransition
-- @see Noble.isTransitioning
-- @see NobleScene
-- @see Noble.Transition
Expand All @@ -254,6 +257,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,
Expand All @@ -266,13 +310,18 @@ end

function Noble.transitionStartHandler()
isTransitioning = true
if (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.
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.
Expand All @@ -285,7 +334,14 @@ 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
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.
end
end

--- Get the current scene object
Expand Down
17 changes: 16 additions & 1 deletion modules/Noble.Transition.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -135,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
Expand Down Expand Up @@ -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.
Expand Down