Credits: This tutorial was created by David Scheller who has kindly allowed me to post it here.
Duration: 30 minutes
This tutorial is an extention of Lime’s “Animated Characters” tutrorial. In this tutorial we will create a user interface which will allow you to start your program, go to multiple screens, return to your main screen, and then finally exit the application gracefully. This will be done using Director Class from here. It’s a good idea to wade through the video tutorial that Ricardo Rauber has on his blog, but this tutorial will show all the steps to make it work.
Step 1: Getting your map
We will be using the map that was created earlier that has our little Mario guy running back and forth across the screen using the arrow buttons, and jumping when we press the “A” button.
Step 2: Adding Director Class to your Project.
Let’s start with a new folder, and add files from DIRECTOR CLASS and LIME.
Director class is a single LUA file that can be downloaded from the above link. The download contains a full working project, but all you need is the one file – DIRECTOR.LUA. For simplicity’s sake we will use a couple of the other files as well. So download the latest version of Director Class and copy the DIRECTOR.LUA , BUILD.LUA, CONFIG.LUA, MAIN.LUA, and UI.LUA.
If you look at the MAIN.LUA file, you will see that it is basically just a pointer to file called SCREEN1.LUA. There is no need to make any changes to the MAIN.LUA file.
We will now create SCREEN1.LUA. Create a new LUA file and enter the following code:
Note the line that reads “localGroup:insert(back)”. This is what adds the blue background to Director and allows it to manage this image.
If you run you application now, you should get a nice blue screen. It doesn’t look like much, but it means that you have succeded in using director to move through two LUA files – the MAIN.LUA and the SCREEN1.LUA.
What does it all mean?
The main thing you want to grasp from SCREEN1.LUA is the first 4 lines of code and the last 3 lines of code. To make it work you need to create a function, create a localGroup, return a localGroup, and end the function. What’s between Creating the group and returning the group is where the fun is.
Step 3: Adding some Buttons to Screen1.
Let’s throw two buttons onto our pretty blue screen. Using basic Corona code, create a PLAY button and an EXIT button. Use your favorite button editor, or use what’s in my code. Add the following code to SCREEN1.LUA, after the localGroup:insert(back) line and before the “return localGroup” code – – – and make sure the related image files are in your project folder.
Note the LOCALGROUP:INSERT(xxx) code. This adds the button to the DIRECTOR CLASS loaclGroup so that when you change screens, director will remove the buttons from the display. If you want to see how important the INSERT is – remove it, and change screens.
Note that our buttons also have insert starements after them, allowing Director to mange them as well.
Barring any unforeseen issues, you should now have a nice blue screen with a PLAY and an EXIT button at the bottom.
Step 4: Making the Buttons work.
Before we add the button functions to SCREEN1, we need to make sure that we have SCREEN2 ready. Since we want the PLAY button to send us to SCREEN2, it needs to be there, or we will just go to limbo.
So create a new LUA called SCREEN2.LUA, and add the default code to it like we did in STEP 2.
After you have created your SCREEN2.LUA file, add the following code to your SCREEN1.LUA file.
This is very straight forward. You are simple telling the application to use director to go to screen2 when the Play button is pressed.
Later we will create a button in SCREEN2 that will bring us back to SCREEN1. But for now, lets finish our SCREEN1.LUA code and create the code to EXIT our application when we are done. Add the following to SCREEN1.LUA.
This is a good thing to have in a professional program. You always want to have a way to cleanly exit the program, so that it’s not running in the background. This doesn’t affect pressing the home button on your phone.
Step 5: Add a BACK button to SCREEN2.
Let’s begin by adding a back button to our SCREEN2.LUA file. Add the following code, making sure that you have the corresponding button image in your project folder.
(Note that I have moved the INSERT command to the bottom of the code. This will come in handy later.)
When you run your program you should now be able to return to your main screen from screen 2.
The code up to this point make a good template to use for future projects. So you might want to save a copy of this project folder. From this point, you can add any map to the code and have the same interface controls.
Step 6: Add the LIME code to Screen2 (FINALLY!).
Now that we have SCREEN2 setup, we can drop our LIME code into the mix.
First off you need to copy all of the LIME files into your project folder.
Any code that you paste into SCREEN2.LUA will be executed when SCREEN2 is called. So to begin with, all we need to do is paste our LIME code into SCREEN2. There is more to it than that, but that is a good starting point. Open the ANIMATEDCHARACTERS/MAIN.LUA file and copy all of the code – then paste it into our SCREEN2.LUA file above the code for creating our back button.
NOTE: THIS CODE REPLICATES THE CREATION OF YOUR BACKGROUND. SO YOU WILL WANT TO DELETE the three lines that came from the ANIMATEDCHARACTERS file.
This code references several external files, so you will need to make sure to copy all of the needed files into your project folder before continuing. Copy all the PNG images and the TUTORIAL11.TMX file.
When you run this code, and press the play button, you should get your game on the screen.
But wait – what happens when we press the back button? Remember the “INSERT”command we worked with earlier? At this point we have inserted the BACK button into the localGroup, and then just pasted the other images from our code on top of it. Director has no control over the new images. This is probably the most complicated part of using director class. Once you get past that, it all flows fairly smoothly.
Any objects that are displayed on your screen need to have an insert statement associated with them. To simplify the process, here are the additional items you need to insert to make your code work properly. Add them in the section at the bottom of the SCREEN2.LUA file before the BACK BUTTON insert.
It is general practice to put these inserts with the images that you are inserting. I like to put them at the end, so I can rearrange them easily if I want to. It’s important to make sure you insert them in the right order, as the order creates layers. The first item inserted is on the bottom layer and the last item is on top. You can play around with the order to see what I mean. Inserting the buttons first will remove them from view – not a desired result.
Step 7: A bit of clean-up.
If you run this code, everything should work nicely. You should be able to hit the PLAY button, go to your game, and the hit the back button to leave the game, then hit exit to leave the game. But there is one final trick that needs to be added.
If you enter your game, then exit to the main screen – then look at the Corona console – you will see a long list of repeated errors running. This is due to creating an “Runtime:addEventListener”. This is one of the objects that does not get removed automatically when DIRECTOR changes screens. You have created a listener for the RUNTIME which stops once you leave SCREEN2. The listener sees that there is no object to listen to, and returns an error.
To resolve this we need to execute a “Runtime:removeEventListener” when we press the BACK BUTTON. So we want to add a line to our pressBack function.
Now you should be able to hop back and forth from SCREEN1 to SCREEN2 with no errors.