Difference between revisions of "SceneManager"
(added some more explanations) |
m (added disclaimer about adding a different scene between the reloading of the same scene.) |
||
(10 intermediate revisions by 2 users not shown) | |||
Line 3: | Line 3: | ||
'''Supported platforms:''' [[File:Platform android.png]][[File:Platform ios.png]][[File:Platform pc.png]][[File:Platform mac.png]][[File:Platform winrt.png]][[File:Platform win32.png]]<br/> | '''Supported platforms:''' [[File:Platform android.png]][[File:Platform ios.png]][[File:Platform pc.png]][[File:Platform mac.png]][[File:Platform winrt.png]][[File:Platform win32.png]]<br/> | ||
'''Available since:''' 2020.2<br/> | '''Available since:''' 2020.2<br/> | ||
− | '''Inherits from:''' [[ | + | '''Inherits from:''' [[Sprite]]<br/> |
=== Description === | === Description === | ||
− | An easy way to manage scenes. | + | An easy way to manage scenes with transitions. |
− | < | + | |
+ | '''Note''': works in pair with the [[Easing]] plugin | ||
+ | |||
+ | |||
+ | First you need to add the plugins to your project: '''right click Plugins -> Add plugin -> SceneManager''' (please do the same for the '''Easing''' plugin). | ||
+ | |||
+ | Then you need to '''require''' the plugins: | ||
+ | <syntaxhighlight lang="lua"> | ||
require "scenemanager" | require "scenemanager" | ||
− | </ | + | require "easing" |
− | + | </syntaxhighlight> | |
− | === | + | === Declaring and Changing Scenes === |
− | + | In your '''main.lua''' file | |
− | < | + | <syntaxhighlight lang="lua"> |
require "scenemanager" | require "scenemanager" | ||
require "easing" | require "easing" | ||
Line 22: | Line 29: | ||
["menu"] = Menu, | ["menu"] = Menu, | ||
["level01"] = Level01, | ["level01"] = Level01, | ||
+ | -- ... | ||
} | } | ||
) | ) | ||
Line 27: | Line 35: | ||
-- from app start to menu | -- from app start to menu | ||
scenemanager:changeScene("menu") | scenemanager:changeScene("menu") | ||
− | + | </syntaxhighlight> | |
− | + | ||
− | + | The scene manager is set up. | |
+ | |||
+ | '''Please be aware''' that you should not switch scene just by reloading the same scene with different variable values, or Gideros might not be able to properly clean up the referenced stuff. '''Always put another scene in between''' (even a blank one should work: see https://forum.gideros.rocks/discussion/comment/68994/#Comment_68994 ) | ||
− | + | === A Scene Class === | |
+ | You can create all your scenes as you please. For example, you can create a folder called "'''scenes'''" and create a file for each scenes ("''menu.lua''", "''level01.lua''", ...). | ||
− | + | Below is what a scene class may look like (feel free to copy paste it): | |
− | < | + | <syntaxhighlight lang="lua"> |
− | + | Menu = Core.class(Sprite) | |
− | function | + | function Menu:init() |
− | -- | + | -- bg |
application:setBackgroundColor(0x1234AA) | application:setBackgroundColor(0x1234AA) | ||
− | + | --... | |
− | -- | + | -- listeners |
self:addEventListener("enterBegin", self.onTransitionInBegin, self) | self:addEventListener("enterBegin", self.onTransitionInBegin, self) | ||
self:addEventListener("enterEnd", self.onTransitionInEnd, self) | self:addEventListener("enterEnd", self.onTransitionInEnd, self) | ||
Line 48: | Line 59: | ||
end | end | ||
− | -- | + | -- game loop |
− | function | + | function Menu:onEnterFrame(e) |
end | end | ||
− | -- | + | -- event listeners |
− | function | + | function Menu:onTransitionInBegin() |
self:addEventListener(Event.ENTER_FRAME, self.onEnterFrame, self) | self:addEventListener(Event.ENTER_FRAME, self.onEnterFrame, self) | ||
end | end | ||
− | + | function Menu:onTransitionInEnd() | |
− | function | ||
self:myKeysPressed() | self:myKeysPressed() | ||
end | end | ||
− | + | function Menu:onTransitionOutBegin() | |
− | function | ||
self:removeEventListener(Event.ENTER_FRAME, self.onEnterFrame, self) | self:removeEventListener(Event.ENTER_FRAME, self.onEnterFrame, self) | ||
end | end | ||
− | + | function Menu:onTransitionOutEnd() | |
− | function | ||
end | end | ||
− | -- | + | -- keys handler |
− | function | + | function Menu:myKeysPressed() |
self:addEventListener(Event.KEY_DOWN, function(e) | self:addEventListener(Event.KEY_DOWN, function(e) | ||
− | + | if e.keyCode == KeyCode.BACK or e.keyCode == KeyCode.ESC then -- for mobiles and desktops | |
− | if e.keyCode == KeyCode.BACK or e.keyCode == KeyCode.ESC then | + | application:exit() |
− | scenemanager:changeScene(" | + | elseif e.keyCode == KeyCode.ENTER then |
+ | scenemanager:changeScene("level01", 1, SceneManager.moveFromLeft, easing.outBack) | ||
+ | -- scenemanager:changeScene("level01", 1, transitions[2], easings[2]) -- nicer | ||
end | end | ||
end) | end) | ||
end | end | ||
− | </ | + | </syntaxhighlight> |
+ | |||
+ | === Transitions and Easings table (optional) === | ||
+ | A nicer way to apply effects for scene transitions is to store them in tables. In your ''main.lua'' you can add at the bottom those tables: | ||
+ | <syntaxhighlight lang="lua"> | ||
+ | transitions = { | ||
+ | SceneManager.moveFromRight, -- 1 | ||
+ | SceneManager.moveFromLeft, -- 2 | ||
+ | SceneManager.moveFromBottom, -- 3 | ||
+ | SceneManager.moveFromTop, -- 4 | ||
+ | SceneManager.moveFromRightWithFade, -- 5 | ||
+ | SceneManager.moveFromLeftWithFade, -- 6 | ||
+ | SceneManager.moveFromBottomWithFade, -- 7 | ||
+ | SceneManager.moveFromTopWithFade, -- 8 | ||
+ | SceneManager.overFromRight, -- 9 | ||
+ | SceneManager.overFromLeft, -- 10 | ||
+ | SceneManager.overFromBottom, -- 11 | ||
+ | SceneManager.overFromTop, -- 12 | ||
+ | SceneManager.overFromRightWithFade, -- 13 | ||
+ | SceneManager.overFromLeftWithFade, -- 14 | ||
+ | SceneManager.overFromBottomWithFade, -- 15 | ||
+ | SceneManager.overFromTopWithFade, -- 16 | ||
+ | SceneManager.fade, -- 17 | ||
+ | SceneManager.crossFade, -- 18 | ||
+ | SceneManager.flip, -- 19 | ||
+ | SceneManager.flipWithFade, -- 20 | ||
+ | SceneManager.flipWithShade, -- 21 | ||
+ | } | ||
+ | easings = { | ||
+ | easing.inBack, -- 1 | ||
+ | easing.outBack, -- 2 | ||
+ | easing.inOutBack, -- 3 | ||
+ | easing.inBounce, -- 4 | ||
+ | easing.outBounce, -- 5 | ||
+ | easing.inOutBounce, -- 6 | ||
+ | easing.inCircular, -- 7 | ||
+ | easing.outCircular, -- 8 | ||
+ | easing.inOutCircular, -- 9 | ||
+ | easing.inCubic, -- 10 | ||
+ | easing.outCubic, -- 11 | ||
+ | easing.inOutCubic, -- 12 | ||
+ | easing.inElastic, -- 13 | ||
+ | easing.outElastic, -- 14 | ||
+ | easing.inOutElastic, -- 15 | ||
+ | easing.inExponential, -- 16 | ||
+ | easing.outExponential, -- 17 | ||
+ | easing.inOutExponential, -- 18 | ||
+ | easing.linear, -- 19 | ||
+ | easing.inQuadratic, -- 20 | ||
+ | easing.outQuadratic, -- 21 | ||
+ | easing.inOutQuadratic, -- 22 | ||
+ | easing.inQuartic, -- 23 | ||
+ | easing.outQuartic, -- 24 | ||
+ | easing.inOutQuartic, -- 25 | ||
+ | easing.inQuintic, -- 26 | ||
+ | easing.outQuintic, -- 27 | ||
+ | easing.inOutQuintic, -- 28 | ||
+ | easing.inSine, -- 29 | ||
+ | easing.outSine, -- 30 | ||
+ | easing.inOutSine, -- 31 | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | === See also === | ||
+ | '''[[UI_Buttons]]''' | ||
{|- | {|- | ||
| style="width: 50%; vertical-align:top;"| | | style="width: 50%; vertical-align:top;"| | ||
=== Methods === | === Methods === | ||
− | [[ | + | [[SceneManager.new]] ''creates a new SceneManager object''<br/><!-- GIDEROSMTD:SceneManager.new(table) creates a new SceneManager object --> |
− | [[ | + | [[SceneManager:changeScene]] ''transitions to a scene''<br/><!-- GIDEROSMTD:SceneManager:changeScene(scene, duration, transition, ease, options) transitions to a scene --> |
| style="width: 50%; vertical-align:top;"| | | style="width: 50%; vertical-align:top;"| | ||
=== Events === | === Events === | ||
− | [[ | + | [[SceneManager_enterBegin|"enterBegin"]] ''Scene is being entered'' <br/><!--GIDEROSEVT:enterBegin Scene is being entered--> |
− | [[ | + | [[SceneManager_enterEnd|"enterEnd"]] ''Scene has been entered'' <br/><!--GIDEROSEVT:enterEnd Scene has been entered--> |
− | [[ | + | [[SceneManager_exitBegin|"exitBegin"]] ''Scene is being exited''<br/><!--GIDEROSEVT:exitBegin Scene is being exited--> |
− | [[ | + | [[SceneManager_exitEnd|"exitEnd"]] ''Scene has been exited'' <br/><!--GIDEROSEVT:exitEnd Scene has been exited--> |
+ | |||
=== Constants === | === Constants === | ||
− | SceneManager.moveFromRight<br/><!-- GIDEROSCST:SceneManager.moveFromRight--> | + | SceneManager.moveFromRight ''Move from the right'' <br/><!--GIDEROSCST:SceneManager.moveFromRight Move from the right--> |
− | SceneManager.moveFromLeft<br/><!-- GIDEROSCST:SceneManager.moveFromLeft--> | + | SceneManager.moveFromLeft ''Move from the left'' <br/><!--GIDEROSCST:SceneManager.moveFromLeft Move from the left--> |
− | SceneManager.moveFromBottom<br/><!-- GIDEROSCST:SceneManager.moveFromBottom--> | + | SceneManager.moveFromBottom ''Move from the bottom'' <br/><!--GIDEROSCST:SceneManager.moveFromBottom Move from the bottom--> |
− | SceneManager.moveFromTop<br/><!-- GIDEROSCST:SceneManager.moveFromTop--> | + | SceneManager.moveFromTop ''Move from the top'' <br/><!--GIDEROSCST:SceneManager.moveFromTop Move from the top--> |
− | SceneManager.moveFromRightWithFade<br/><!-- GIDEROSCST:SceneManager.moveFromRightWithFade--> | + | SceneManager.moveFromRightWithFade ''Move from the right with fading'' <br/><!--GIDEROSCST:SceneManager.moveFromRightWithFade Move from the right with fading--> |
− | SceneManager.moveFromLeftWithFade<br/><!-- GIDEROSCST:SceneManager.moveFromLeftWithFade--> | + | SceneManager.moveFromLeftWithFade ''Move from the left with fading'' <br/><!--GIDEROSCST:SceneManager.moveFromLeftWithFade Move from the left with fading--> |
− | SceneManager.moveFromBottomWithFade<br/><!-- GIDEROSCST:SceneManager.moveFromBottomWithFade--> | + | SceneManager.moveFromBottomWithFade ''Move from the bottom with fading'' <br/><!--GIDEROSCST:SceneManager.moveFromBottomWithFade Move from the bottom with fading--> |
− | SceneManager.moveFromTopWithFade<br/><!-- GIDEROSCST:SceneManager.moveFromTopWithFade--> | + | SceneManager.moveFromTopWithFade ''Move from the top with fading'' <br/><!--GIDEROSCST:SceneManager.moveFromTopWithFade Move from the top with fading--> |
− | SceneManager.overFromRight<br/><!-- GIDEROSCST:SceneManager.overFromRight--> | + | SceneManager.overFromRight ''Slide over from the right'' <br/><!--GIDEROSCST:SceneManager.overFromRight Slide over from the right--> |
− | SceneManager.overFromLeft<br/><!-- GIDEROSCST:SceneManager.overFromLeft--> | + | SceneManager.overFromLeft ''Slide over from the left'' <br/><!--GIDEROSCST:SceneManager.overFromLeft Slide over from the left--> |
− | SceneManager.overFromBottom<br/><!-- GIDEROSCST:SceneManager.overFromBottom--> | + | SceneManager.overFromBottom ''Slide over from the bottom'' <br/><!--GIDEROSCST:SceneManager.overFromBottom Slide over from the bottom--> |
− | SceneManager.overFromTop<br/><!-- GIDEROSCST:SceneManager.overFromTop--> | + | SceneManager.overFromTop ''Slide over from the top'' <br/><!--GIDEROSCST:SceneManager.overFromTop Slide over from the top--> |
− | SceneManager.overFromRightWithFade<br/><!-- GIDEROSCST:SceneManager.overFromRightWithFade--> | + | SceneManager.overFromRightWithFade ''Slide over from the right with fading'' <br/><!--GIDEROSCST:SceneManager.overFromRightWithFade Slide over from the right with fading--> |
− | SceneManager.overFromLeftWithFade<br/><!-- GIDEROSCST:SceneManager.overFromLeftWithFade--> | + | SceneManager.overFromLeftWithFade ''Slide over from the left with fading'' <br/><!--GIDEROSCST:SceneManager.overFromLeftWithFade Slide over from the left with fading--> |
− | SceneManager.overFromBottomWithFade<br/><!-- GIDEROSCST:SceneManager.overFromBottomWithFade--> | + | SceneManager.overFromBottomWithFade ''Slide over from the bottom with fading'' <br/><!--GIDEROSCST:SceneManager.overFromBottomWithFade Slide over from the bottom with fading--> |
− | SceneManager.overFromTopWithFade<br/><!-- GIDEROSCST:SceneManager.overFromTopWithFade--> | + | SceneManager.overFromTopWithFade ''Slide over from the top with fading'' <br/><!--GIDEROSCST:SceneManager.overFromTopWithFade Slide over from the top with fading--> |
− | SceneManager.fade<br/><!-- GIDEROSCST:SceneManager.fade--> | + | SceneManager.fade ''Fade over'' <br/><!--GIDEROSCST:SceneManager.fade Fade over--> |
− | SceneManager.crossFade<br/><!-- GIDEROSCST:SceneManager.crossFade--> | + | SceneManager.crossFade ''Cross fade'' <br/><!--GIDEROSCST:SceneManager.crossFade Cross fade--> |
− | SceneManager.flip<br/><!-- GIDEROSCST:SceneManager.flip--> | + | SceneManager.flip ''Flip'' <br/><!--GIDEROSCST:SceneManager.flip Flip--> |
− | SceneManager.flipWithFade<br/><!-- GIDEROSCST:SceneManager.flipWithFade--> | + | SceneManager.flipWithFade ''Flip with fading'' <br/><!--GIDEROSCST:SceneManager.flipWithFade Flip with fading--> |
− | SceneManager.flipWithShade<br/><!-- GIDEROSCST:SceneManager.flipWithShade--> | + | SceneManager.flipWithShade ''Flip with shading'' <br/><!--GIDEROSCST:SceneManager.flipWithShade Flip with shading--> |
|} | |} | ||
{{GIDEROS IMPORTANT LINKS}} | {{GIDEROS IMPORTANT LINKS}} |
Latest revision as of 22:25, 19 June 2024
Supported platforms:
Available since: 2020.2
Inherits from: Sprite
Description
An easy way to manage scenes with transitions.
Note: works in pair with the Easing plugin
First you need to add the plugins to your project: right click Plugins -> Add plugin -> SceneManager (please do the same for the Easing plugin).
Then you need to require the plugins:
require "scenemanager"
require "easing"
Declaring and Changing Scenes
In your main.lua file
require "scenemanager"
require "easing"
scenemanager = SceneManager.new(
{
["menu"] = Menu,
["level01"] = Level01,
-- ...
}
)
stage:addChild(scenemanager)
-- from app start to menu
scenemanager:changeScene("menu")
The scene manager is set up.
Please be aware that you should not switch scene just by reloading the same scene with different variable values, or Gideros might not be able to properly clean up the referenced stuff. Always put another scene in between (even a blank one should work: see https://forum.gideros.rocks/discussion/comment/68994/#Comment_68994 )
A Scene Class
You can create all your scenes as you please. For example, you can create a folder called "scenes" and create a file for each scenes ("menu.lua", "level01.lua", ...).
Below is what a scene class may look like (feel free to copy paste it):
Menu = Core.class(Sprite)
function Menu:init()
-- bg
application:setBackgroundColor(0x1234AA)
--...
-- listeners
self:addEventListener("enterBegin", self.onTransitionInBegin, self)
self:addEventListener("enterEnd", self.onTransitionInEnd, self)
self:addEventListener("exitBegin", self.onTransitionOutBegin, self)
self:addEventListener("exitEnd", self.onTransitionOutEnd, self)
end
-- game loop
function Menu:onEnterFrame(e)
end
-- event listeners
function Menu:onTransitionInBegin()
self:addEventListener(Event.ENTER_FRAME, self.onEnterFrame, self)
end
function Menu:onTransitionInEnd()
self:myKeysPressed()
end
function Menu:onTransitionOutBegin()
self:removeEventListener(Event.ENTER_FRAME, self.onEnterFrame, self)
end
function Menu:onTransitionOutEnd()
end
-- keys handler
function Menu:myKeysPressed()
self:addEventListener(Event.KEY_DOWN, function(e)
if e.keyCode == KeyCode.BACK or e.keyCode == KeyCode.ESC then -- for mobiles and desktops
application:exit()
elseif e.keyCode == KeyCode.ENTER then
scenemanager:changeScene("level01", 1, SceneManager.moveFromLeft, easing.outBack)
-- scenemanager:changeScene("level01", 1, transitions[2], easings[2]) -- nicer
end
end)
end
Transitions and Easings table (optional)
A nicer way to apply effects for scene transitions is to store them in tables. In your main.lua you can add at the bottom those tables:
transitions = {
SceneManager.moveFromRight, -- 1
SceneManager.moveFromLeft, -- 2
SceneManager.moveFromBottom, -- 3
SceneManager.moveFromTop, -- 4
SceneManager.moveFromRightWithFade, -- 5
SceneManager.moveFromLeftWithFade, -- 6
SceneManager.moveFromBottomWithFade, -- 7
SceneManager.moveFromTopWithFade, -- 8
SceneManager.overFromRight, -- 9
SceneManager.overFromLeft, -- 10
SceneManager.overFromBottom, -- 11
SceneManager.overFromTop, -- 12
SceneManager.overFromRightWithFade, -- 13
SceneManager.overFromLeftWithFade, -- 14
SceneManager.overFromBottomWithFade, -- 15
SceneManager.overFromTopWithFade, -- 16
SceneManager.fade, -- 17
SceneManager.crossFade, -- 18
SceneManager.flip, -- 19
SceneManager.flipWithFade, -- 20
SceneManager.flipWithShade, -- 21
}
easings = {
easing.inBack, -- 1
easing.outBack, -- 2
easing.inOutBack, -- 3
easing.inBounce, -- 4
easing.outBounce, -- 5
easing.inOutBounce, -- 6
easing.inCircular, -- 7
easing.outCircular, -- 8
easing.inOutCircular, -- 9
easing.inCubic, -- 10
easing.outCubic, -- 11
easing.inOutCubic, -- 12
easing.inElastic, -- 13
easing.outElastic, -- 14
easing.inOutElastic, -- 15
easing.inExponential, -- 16
easing.outExponential, -- 17
easing.inOutExponential, -- 18
easing.linear, -- 19
easing.inQuadratic, -- 20
easing.outQuadratic, -- 21
easing.inOutQuadratic, -- 22
easing.inQuartic, -- 23
easing.outQuartic, -- 24
easing.inOutQuartic, -- 25
easing.inQuintic, -- 26
easing.outQuintic, -- 27
easing.inOutQuintic, -- 28
easing.inSine, -- 29
easing.outSine, -- 30
easing.inOutSine, -- 31
}
See also
MethodsSceneManager.new creates a new SceneManager object SceneManager:changeScene transitions to a scene |
Events"enterBegin" Scene is being entered ConstantsSceneManager.moveFromRight Move from the right |