Word Clock – Part 1

Let’s go

I assume you have installed Corona SDK und Sublime Editor. If not I recommend to read this installation instruction to get Corona SDK and Sublime Text Editor running.

If your development environment with Corona SDK is running, you can go on with this course.

If you are not using Sublime Text: This doesn’t really matter. You should be able to adapt the Sublime descriptions to your IDE.

If you do not know what we want to achieve in this course, please read the introduction first.

Creating a new project

After you have installed Corona SDK you can start the Corona Simulator app and you will get the following screen. If you start the Corona Simulator for the first time the Simulator asks you to enter your Corona developer credentials.

Corona Simulator Start Screen

Corona Simulator Start Screen

Corona Simulator Developer Login

Corona Simulator Developer Login

To create a fresh new project click on NEW PROJECT.

Enter a name for your new project. In this case we choose Wordclock.

Next choose Blank from the List of Templates.

And leave all other settings at their default values. In this course I will show you how to setup everything from scratch. So we do not need any template code.

Press Next (on Mac) or OK (on Windows) to create the Project.

 

New Project Form

New Project Form

A file requester asks you where to save the project. I show you how I do organize my projects.

If you are a starter I recommend to follow this structure, but of course you are free to choose your own.

I have a folder where all my Corona Projects are located in i.e. Corona-Projects. In this Folder I create new folder called WordclockProject. In the requester change into this new folder WordclockProject and click on create.

Now you will be asked if you want to open the new project in the editor or in the Explorer/Finder. Choose to open in Explorer/Finder to see what has happened.

Now you should have the following folder and files structure:

File & Folder Structure of the new created project

File & Folder Structure of the new created project

The Files of a Corona SDK Project

The minimum files of a Corona SDK project are three files:

  • main.lua
  • config.lua
  • build.settings

The main.lua contains the starting point of your code. Corona does always look for a main.lua file.

The config.lua contains the settings of your project like the screen resolution.

The build.settings contains further settings to add the supported orientations, default orientations but also which plugins or device features the app should support.

As you can see in the screenshot above there are many Icon files and a Default-568h@2x.png.

What are those?

The Default-xxx image is the launch image screen that is needed for iOS apps.

This image closes the small waiting gap between tapping the app icon to launch and the first screen the app can display.

Apple wants to create a seamless experience.

The launch image is NOT intended to show team logos or a “Loading…” message in general. It should just simulate your first screen of the app itself.

Nevertehless, if your very first screen of the app IS a “Loading…” message, it does make sense to create a launch image that shows the “Loading…” message too.

The big list of icons in the folder is needed to cover all the different devices and its resolutions on iOS and Android.

In fact you have to create over 50 icons and launch images to cover an android and iOS app requirements for their app stores.

?

But don’t be afraid. I have a solution fort this too, but more on this later on.

Create a Project in Sublime Editor

To use your Corona Projects in a convenient way in Sublime, I highly recommend to create a project in Sublime.

With a project in Sublime you can put all files that belong to your project in one system. So if you open a project you have all files you need at place.

This is not self-evident since Sublime is an all purpose developer text editor. It is not an IDE that has been specifically built for Corona SDK.

If not already in view, open the side bar in Sublime Editor to see a folder structure. In the top menu click View>Side Bar>Show Side Bar.

Now open the Finder/Explorer and goto to your Wordclock-Project folder. Drag the whole Wordclock-Project folder and drop it to Sublime’s side bar.

Use the little arrows in the side bar to show all files in the folders.

Sublime's Side Bar With Project Files

Sublime’s Side Bar With Project Files

The last but very important step is to tell Sublime that this is a project.

To do so click in Sublime’s menu on Project>Save Project As.

A file requester pops up and asks you where to save the sublime-project file. In this file Sublime saves the informations and settings for this project (which files, which syntax etc.).

So in the file requester again choose your Wordclock-Project folder and save the file as wordclock.sublime-project there.

Why not using the Wordclock folder?

Everything in the Wordclock folder is only related to Corona SDK and the app itself.

All other files, like this Sublime project file or Photoshop files or anything else that will not be referenced directly in your app should be stored outside the Wordclock folder.

The Wordclock folder should only contain files that will be compiled into the final binaries which are uploaded to the App Stores like the PNGs for your in-game graphics or the wave files you play in your app.

But the artwork files, of which you create these PNGs (Photoshop, Affinity Designer etc.) should stay outside the Wordclock folder in its parent the Wordclock-Project folder.

Now you know why I recommend a parent project level folder. Here you can create other folder for your artwork files, music tracks etc.

The following Screenshot shows a typical project folder setup of mine, with an Artwork and Music folder outside the Corona SDK folder.

Complete Folder Structure

Complete Folder Structure

To open this Sublime project you can use the Project>Open Project….

Additionally, chances are high that this project is listed in the Project>Open Recent list which is my favored workflow:

  1. Open Sublime
  2. Go to the Project>Open Recent list
  3. Click on the project I want to work on

Now that our project have been setup let’s do a quick „Hello World“. If you are not a Corona/Lua beginner you can skip this last step.

Hello World

At least one file of your project should be opened to compile your project . So in Sublime’s side bar click on the main.lua file to open it in the editor pane. It does only contain some comments.

If the Corona Editor plugin is installed in Sublime you can now press Cmd+F10 or in the menu click Corona Editor>Run Project.

Now the Corona Simulator starts compiling your project and displays the results: a black window. Furthermore Sublime’s console pane has opened and printed out some informations. It should look similar to the following screen.

Compiling an empty project

Compiling an empty project

In the main.lua, you will find the following line:

-- Your code here

Replace it with this line:

print("Hello World")

Press Cmd+F10 again to compile it. Unfortunately you will still see a black screen. But have a look at the console pane. The last line should be our Hello World string.

Ok, but now we want to get our Hello World to show up in the simulator. To do this, add the following line to the main.lua after the print(“Hello World”):

display.newText("Hello World", 150, 180, native.systemFont, 25)

If you have not closed the simulator und just hit Cmd+S to save the main.lua file, the simulator will automatically re-start the new code. This is very convenient.

If you have closed the simulator you need to run the code again with Cmd+F10. Now you should see the Hello World on the simulator screen.

The final Hello World

The final Hello World

display.newText() is a Corona SDK function to display text on the screen. It needs some parameters in the brackets to control what the function should do. In the example above we used the following paramters.

  1. “Hello World” – this is text string that should be displayed
  2. 150 – the x position on the screen of the displayed text
  3. 180 – the y position on the screen of the displayed text
  4. native.systemFont – a Corona SDK constant to get the standard font of the current device
  5. 25 – the size of the font

“How do I know which parameter I have to use?”

Good question. Therefore we have to take a look into the Corona SDK documentation.

Make sure in the lower right corner of Sublime Editor that the the right Syntax is selected. It must be set to Corona SDK Lua (not Lua alone or any other language). If not, click on that correct label to change the syntax and hit Cmd+S to save the file (now Sublime remembers the syntax settings for this file).

Then in the code click on the display.newText command. The cursor must be in or right before display.newText. Now hit F1.

Your default internet browser should start und you will be directed automatically to the online documentation for the display.newText() command. In this documentation you will get every information and possible parameters about the function. I highly recommend to read it.

The Corona SDK online documentation is found here: https://docs.coronalabs.com/

By the way: if you wonder why in the last screenshots the simulator looks different: it’s a feature of the simulator. You can change the simulated device. When the simulator is active (click on it) hit Window>View As.

Then choose from the list of devices. This is especially handy if you want to check layouts on smartphone and tablet devices.

List of simulator devices

List of simulator devices

Conclusion

Congrats! You made the first steps by Installing Corona SDK and Sublime Editor. You learned a proper way to organize your project folders and how to create a project in Sublime Editor. And you already passed the mandatory „Hello World“ project with Corona SDK and its Lua language.

You also learned how to print to console and you made your first output on the simulator screen itself. I also showed you how to use the Corona SDK documentation.

In the next part we will have a short look on project planning before we will dive deeper into the Corona SDK.

– René