Switching from Director to Storyboard API

Solar2D General Questions/Discussion
#1

Hello,

I am planning to switch all Kwik projects from Director class to the new Storyboard API. Unfortunately I couldn’t have time to go deep into the new API and I was wondering if someone else have already made this transition, and is willing to share a few tips.

Here how Kwik works currently:
Main.lua

local director = require("director")   
-- Create a main group  
local mainGroup = display.newGroup()  
local initPage = 1  
  
-- Main function  
local function main()  
 mainGroup:insert(director.directorView)   
 director:changeScene( "page\_"..initPage )  
 return true  
end  
main()

page_1.lua

module(..., package.seeall)   
imgDir = ""   
audioDir = ""   
  
 function new()   
 local numPages = 1   
 local menuGroup = display.newGroup()   
  
 local curPage = 1   
  
 local drawScreen = function()   
 local Firearea   
 Firearea = display.newImageRect( imgDir.. "p1\_firearea.png", 1024, 768 );   
 Firearea.x = 512; Firearea.y = 384; Firearea.alpha = 1   
 menuGroup:insert(Firearea)   
 menuGroup.Firearea = Firearea   
  
 local function flip (event)   
 if event.phase =="ended" then   
 if event.xStart \< event.x and (event.x - event.xStart) \>= 30 then   
 if (curPage \> 1) then   
 director:changeScene( "page\_"..curPage-1, "moveFromLeft" )   
 end   
 elseif event.xStart \> event.x and (event.xStart-event.x) \>= 30 then   
 if (curPage \< numPages) then   
 director:changeScene("page\_"..curPage+1, "moveFromRight")   
 end   
 end   
 end   
 end   
 Firearea:addEventListener("touch", flip)   
 end   
 drawScreen()   
  
 return menuGroup   
end

As you can see, basically Director appears here only as repository (menuGroup) and to move between scenes.

Checking the auto created code for the new e-book template, it seems a little confuse when to use or not the several functions like scene:enterScene, exitScene, destroyScene and createScene.

In Main.lua the example is simple:

local storyboard = require "storyboard"  
storyboard.gotoScene( "title" )

However, in both title.lua and page1.lua there are lots of code that are far from needed (or at least they are not exposed) in Director.

Questions are:

  • do I need to create all scene:functions for each page?
  • what is the best way to keep all scene elements under a single group (like the menuGroup above)?
  • do I really need to add the require(“storyboard”) in all pages?
  • does anyone has a better or cleaner way to transition from Director to Storyboard?

Thanks a lot,
Alex

[import]uid: 4883 topic_id: 18232 reply_id: 318232[/import]

#2

**Questions are:

  • do I need to create all scene:functions for each page?**

For your menu page, you probably need to create them, but you don’t have to do much if any code for them.

scene:createScene

is where you’re going to do most of your work. Load your background, create your buttons, etc.

scene:enterScene

gets called after the scene is created and here is a place to start animations, assign Runtime:(“enterFrame”, *) event listeners, start timers, etc.

scene:exitScene

would be where you undo all the timers, listeners and such that you started in enterScene

scene:destroyScene

would hold code you would typically put into a director clean() function. In other words destroy objects not in the display group that is returned from createScene.

So createScene is the same as director’s new(), destroyScene is the same as director’s clean() and you have two extra points to deal with stuff that should happen after things are loaded and need to end before switching screens.

One difference with storyboard is that it does keep old scenes around until it needs to free up memory and thus destroyScene gets called at some point in the future when we need memory back. exitScene is there because you don’t want your timers/transitions and such to keep running after you switch scenes and if you come back to a scene, it should be in the same state you left it, so enter Scene is to start those items up again.

Once you get used to it, its a natural “Corona SDK” way of doing things.

- what is the best way to keep all scene elements under a single group (like the menuGroup above)?

storyboard creates a group called “group”. This is the same as the typical director “localGroup” which you seem to have renamed to “menuGroup”.

- do I really need to add the require(“storyboard”) in all pages?
It appears so. But you could load storyboard in your main.lua once and leave off the local, but then it would reside in global space, not local space and as we know, globals are to be avoided when possible.

- does anyone has a better or cleaner way to transition from Director to Storyboard?
I’m not transitioning. I started a new project with Storyboard and its going pretty good. I’ve not tried to convert a director project to storyboard yet.

But as I mentioned above: new becomes scene:createScene, clean becomes scene:destroyScene, rename localGroup to group. You don’t return group anymore. The code returns a scene object. I wouldn’t think it would be that hard, but I’ve not tried it.

Storyboard DOES NOT support popup’s yet, but since your scene isn’t destroyed when you switch away from it, I might be able to set a variable “returnTo” that my popup scenes know to go back to when its said and done. Still working out that little bit. [import]uid: 19626 topic_id: 18232 reply_id: 69753[/import]

#3

Thanks a lot Rob. I will give a try.

I though Director was cleaning pages automatically when switching them. I have never used the Director’s clean() function. [import]uid: 4883 topic_id: 18232 reply_id: 69763[/import]

#4

Rob, that was very helpful to me, too. But I have one question.

Do I have to add all of my display objects to the “group”? [import]uid: 103624 topic_id: 18232 reply_id: 69817[/import]

#5

Yes, and no.

Any objects you want to go away when the scene switches away, needs to be in group. But lets say your building a game with some types of heads of display, inventory box, stuff you want on every screen, no you would not put those into group.

So its the same as with Director. If you would put it in “localGroup” you would put it into “group” with storyboard.
[import]uid: 19626 topic_id: 18232 reply_id: 69821[/import]