Back to Beyond the Codea in-app reference

How Codea executes your code

Introduction

There are six optional functions that you can create in your code which, if they exist, Codea will call in certain circumstances:

These six functions are only entry points into your code.

setup() and draw()

The 'Main' tab of every new Codea project contains default code (which can be changed) with an outline of a setup() and draw() function, as shown below:

-- NameOfProject

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

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

    -- This sets the line thickness
    strokeWidth(5)

    -- Do your drawing here

end

For this reason, setup() and draw() are often implemented in the 'Main' tab of a Codea project. However, they can be implemented in any tab.

touched(touch)

Many Codea projects make use of the touched(touch) function. An example of its use is provided by Codea's Multi Touch example project:

function touched(touch)
    if touch.state == ENDED then
        touches[touch.id] = nil
    else
        touches[touch.id] = touch
    end
end

Basic touches can be handled without using touched(touch) by using the CurrentTouch global variable provided by the Codea API. An example of that is provided by Codea's Handling Touches example project.

function draw()
    noSmooth()

    fill(0, 0, 0, 50)
    rect(0,0,WIDTH,HEIGHT)

    noStroke()

    if CurrentTouch.state == BEGAN then
        fill(16, 178, 197, 255)
    elseif CurrentTouch.state == MOVING then
        fill(255, 0, 0, 255)
    elseif CurrentTouch.state == ENDED then
        fill(210, 218, 16, 255)
    end

    ellipse(CurrentTouch.x, CurrentTouch.y, 100,100)
end

collide(contact)

The 'Physics' chapter of Codea's in-app reference documents most of the collide(contact) function. The Physics API simulates the behaviour of two-dimensional bodies, frame by frame. A contact occurs whenever two of the bodies collide with each other.

myBody:destroy() causes the body referred to by myBody to be removed from the simulation immediately. It is important not to destroy bodies in the collide(contact) function, because it is called during the simulation of all bodies during a particular frame. Destroying a body in this way can cause Codea to crash.

Press Play to run

When you press a Play button to run a project, the following occurs:

1. Each tab in a project, such as the "Main" tab, corresponds to a file of Lua code. The order of the files is the same as the order of the tabs (left to right) in the Codea Editor. That order is initially alphabetical, but can be changed in the Editor.
2. Before any files in your project, or its dependent projects (if any), are loaded, Codea loads and runs a file named LuaSandbox.lua. That file contains Lua code to disable Lua functionality, such as os.exit(), that is considered to be unsafe in the Codea environment.
3. If your project has dependencies, Codea loads and runs the files in each of the dependent projects (other than their "Main" file). The dependent projects are dealt with in the order that they were selected as dependencies. The files in each dependent project are dealt with in order.
4. Once any dependencies have been dealt with, Codea loads and runs the files in the project (including the "Main" file). The files in the project are dealt with in order.
5. When loading and running a file, anything inside a function ... end block is saved for later use. Anything outside of such a block is run.
6. Codea then calls the setup() function.
7. Codea then enters a loop:
   1. Each time round the loop, Codea calls the draw() function (if it exists).
   2. At the end of each loop, Codea looks to see if the screen has been touched. If it has been touched, Codea calls the touched(touch) function (if it exists) once for each touch. Information about the touch in question is passed in the touch argument.
   3. If you are using the Physics API, Codea looks to see if any two bodies have collided. If they have, Codea calls the collide(contact) function (if it exists) once for each collision. Information about the contact in question is passed in the contact argument.
   4. Codea also looks to see if the screen orientation has changed. If it has changed, Codea calls the orientationChanged(newOrientation) function (if it exists). Information about the new orientation is passed in the newOrientation argument.

Use of print() in draw() and touched()

If you add a print() statement in draw() or touched() it will most likely be executed up to 60 times a second, quickly filling the Output pane in the viewer and, ultimately, causing your code to slow as the buffer underlying the Output pane fills.