Skip to content

1. Starting with Codea

March 10, 2013

Codea is the best programming tool I’ve ever worked with, and a joy to work with. But it’s different, and that takes getting used to. I haven’t been using Codea long, so now is a good time to explain what I wish I had learned at the beginning.

Codea is event driven

Codea won’t do anything you don’t tell it to do. It only does two things automatically.

  • run a setup function at the beginning, to do whatever you want before drawing anything
  • redraw the screen 60 times a second with whatever you want to show.

But it can respond to all sorts of things – your finger on the screen, or collisions between objects you’ve put there, or tilting the iPad, and much more.

And it has a lot of great animation features built in, some easy and some difficult to use.

I come from a conventional programming background, where stuff stays on the screen when you put it there, so it was confusing to have to keep redrawing the screen 60 times a second in Codea, to keep it showing.

So what is Codea for?

Codea is designed for animation – getting things to move across the screen. Think of platform games, shoot em up games, puzzle games, pattern matching games – anything like that. You can create App Store quality games – and submit them – and the forum users will usually help you test your beta versions.

Codea can do 3D as well as 2D, but it is way harder. It will be extremely difficult to create anything too meaningful in 3D (and Codea’s speed is a limitation), but it is fun as a way of learning about 3D animation.

But mostly, Codea is fun. It is well designed, relatively easy to learn and use (“relatively easy” because no programming is totally easy, despite the books that say “Learn X in 24 hours”), and a great introduction to game programming. Personally, I have been programming for many years for fun – but I’ve never enjoyed it so much before this.

And don’t be put off by any technical talk in the forum. If you look back at the history, most of today’s experts were asking newbie questions just a year ago. So have a look at the Lua and Codea documentation, these and other tutorials, and, most of all, have a go yourself.

You do need, however, to realise that there isn’t a paved freeway that will take you smoothly to knowledge. For a start, Codea is built on top of another language, Lua, which has been used for years as a scripting language in online games. The Codea community doesn’t have a set of Lua tutorials, and you’ll need to do some looking around, or read the Lua manual. You can probably read these tutorials without learning some Lua first, but it will be harder if you do.

I have tried to fill the gap with some ebooks, starting with

  • Lua – I recommend you start here, if you don’t know Lua. However, if you want to get into Codea, keep reading. The Lua tutorials will be there when you need them.
  •  Codea
  • 3D in Codea
  • and more…

One last thing before we start. This blog uses WordPress, which has one very annoying habit. It doesn’t like double quotes ” or greater than > or less than < signs in code, and changes them into HTML codes. The reason for this is that the ‘greater than’ and ‘less than’ characters are used for HTML tags, so WordPress replaces them with HTML strings that should look the same on the screen, but won’t confuse the web browser. There is a way for me to mark up code so it looks ok, but WordPress does this by replacing the usual characters with special codes – if you copy and paste any of my code out of these posts, you may see this happening, and you need to fix that before running the code. Note – this only applies to code on this blog – any links I give you to code somewhere else should be ok.

So why have I stuck with WordPress? Unfortunately, it took me a few posts to realise, and by then, I was committed.

Getting started

But let’s get started. If you open up Codea and click the “Add New Project” button, and give your project a name, eg Test, you’ll get a page with this:

-- Test

-- Use this function to perform your initial setup
function setup()
    print('Hello World!')

-- This function gets called once every frame
function draw()
    -- This sets a dark background color
    background(40, 40, 50)

    -- This sets the line thickness
    -- Do your drawing here

Note – you’ll see the code above actually uses single quotes around “Hello world”. This is because WordPress has a nasty habit of changing double quotes into a weird sequence of HTML characters. So I will use single quotes all through these tutorials – but in practice (and in the code I’ve stored elsewhere for you to copy), I always use double quotes.

If you press the little run button (the faint arrow at bottom right of the page), you’ll get a mostly blank screen, and “Hello world” in a section on the left.

The left hand section gives you all sorts of help while you’re building a project, like printing out messages. The big black area on the right is our screen, where we will do wonderful things.

Let’s go back to the code. Press the left facing arrow at bottom left of the screen.

The code is made up of two “functions”, one called “setup” and one called “draw”. The setup function runs at the very beginning and lets you set up your project. You’ll see all it does is print “Hello world'”, but remember the print statement. It will be your friend when you get stuck or have errors, because you can print out stuff to see what is happening.

The draw function doesn’t do anything except set background color (ignore the strokeWidth line for now). The numbers in brackets next to background stand for the red, green and blue colors, from a low of 0 to a high of 255. So (0,0,0) is black, (255,255,255) is white, (255,0,0) is red, and so on.

You’ll see these numbers have a yellow circle round them, which means you can select from a palette of colors rather than typing numbers in. Touch the yellow circle and try choosing a color you like. When you’re done, press elsewhere on the screen to dismiss the color picker, then try running the program (arrow at bottom right, remember) to see the result.

Drawing something

But this is a bit dull, so let’s try drawing something, say a line on the screen.

The screen is made up of little pixels, and they are numbered from the bottom left, with a value for x (horizontal) and y (vertical), so if x=40 and y=100, that is the 40th pixel to the right, and 100 pixels up.

So let’s draw a line. Add this under the line “– Do your drawing here”


Then run the program, and you should see a white line appear on screen. It looks permanent, but it’s actually being redrawn 60 times a second.


Let’s animate it a little. Add this line under the “hello world” line up above


And alter the code we just added to draw the line like this:


What we’ve done is made the starting x value of the line into a variable, which starts at 0 on the x axis. We do this in the setup function.

In the draw function we increase x by 1 every time the screen redraws, so when you run it, you’ll see the line swing around and eventually get stuck.

We don’t really want the x value to go beyond the right edge of the screen, but how many pixels is that? Codea can tell us. Under hello world again, add this line


(We add it up here because we only need to print it once. If we put this in the draw function, it would print out 60 times a second!).

And when you run it, you should see two numbers under “Hello world” at the left, the first is for x and the other for y. You can use WIDTH and HEIGHT any time in your code, so lets do that. Under the line x=x+1, put this

if x>WIDTH then x=0 end

which restarts x at 0 if it gets to the right hand side.

Don’t copy the code from above, because WordPress has a nasty habit of turning greater than and less than signs into nonsense code. Copy it from here instead.

And if you run it, you’ll see you have a very slow windscreen wiper.


From → Programming

  1. Ken Duerden permalink

    Many thanks for producing this series of tutorials. I have been using Codea for about a week and the mist is beginning to clear. These tutorials have really helped to blow a lot of it away. I really hope that you continue to develop your tutorials as you have a real gift for explaining the concepts in an easy to understand manner. Thanks.

  2. rffr permalink

    Nice work, I’ll love this tuts, for sure.

  3. I am getting ‘then’ expected near ‘&’ error and I can’t find anything that would answer this. Any ideas?

    • Ah, that would be WordPress stuffing up the code by replacing > with HTML characters.

      Try it now. sorry!

  4. I’m getting then expected near & error please help

  5. — Hello World

    — Use this function to perform your initial setup
    function setup()
    print(‘Hello World!’)
    img=readImage(“SpaceCute:Beetle Ship”)


    — This function gets called once every frame
    function draw()
    — This sets a dark background color
    background(21, 233, 222, 230)

    — This sets the line thickness

    — Do your drawing here
    if&gt;WIDTH then x=0
    fill(78, 8, 229, 81)

    • Benjamin

      the problem is that WordPress has mangled part of the code, you’ll see this by comparing your code with what you saw in my post.

      I’ve now included links in posts 1 and 2 so you can copy the code from somewhere else, and it should run now.

  6. Maybe you could take screenshots instead it means they can’t copy the code but at least it would be accurate and also is there a way of touching the screen to find out what the coordinates are for that place as opposed to typing in separate coordinates ? Thank you for the help

  7. You can use the HTML codes

     and  so wordpress won't mangle your code. Even better, use the wordpress plugin CodeColorer. It hasn't been updated for a long time, but still works great on all releases of WordPress.
    • Jack, I’ve tried HTML every which way.

      I also looked at plugins, but they don’t apply to, only to

Trackbacks & Pingbacks

  1. If you are new here | coolcodea

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: