Clone wiki

Core / CodeaMain

Back to Beyond the Codea in-app reference

FunctionIconOverview-Small.png How Codea executes your code


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

FunctionIts argumentsWhen the function is called by Codea
setup()NoneOnce, after loading the code (see below) and before calling draw() or touched() etc. Most projects implement setup().
draw()NoneUp to 60 times a second, after setup(). Most projects implement draw().
touched(touch)One, a touch userdata value, representing data about a single touch on the screen. See the 'Touch' chapter of Codea's in-app reference.After draw, whenever a touch on the Viewer pane begins, moves or ends. For multiple touches, called once for each touch.
orientationChanged(newOrientation)One, a number value representing the new orientation. See the 'Display' chapter of Codea's in-app reference.When the screen orientation changes, usually due to the iPad being rotated by the user.
keyboard(key)One, a string value representing the key pressed. See the 'Display' chapter of Codea's in-app reference.If the on-screen keyboard is shown using showKeyboard(), when a key is pressed.
collide(contact)One, a contact userdata value, representing data about a single contact between two bodies. See the 'Physics' chapter of Codea's in-app reference.Used together with the Physics API, when two bodies collide with each other in your simulation. For multiple contacts, called once for each contact.

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!")

-- 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


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.


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[] = nil
        touches[] = touch

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()

    fill(0, 0, 0, 50)


    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)

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


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.