Graphics

Codea can draw 2D and 3D graphics.

The draw() function is called once per frame to draw the contents of the screen.

The background(r,g,b,a) function clears the background with a given color. You typically call this once at the start of draw(). When it isn’t called, the contents of the background stay the same as the previous frame.

Draw other elements with functions such as line(), sprite() and rect().

These functions use the current drawing style, which affects things like fill color, stroke color, and stroke width.

Try it: an animated circle

This project draws a circle that moves back and forth across the screen. We use elapsed time to calculate the position of the circle.

function setup()
end

function draw()
    background(24, 28, 38)
    style.fill(100, 220, 200).noStroke()
    local x = WIDTH * (0.5 + 0.25 * math.sin(time.elapsed))
    ellipse(x, HEIGHT / 2, 80, 80)
end

Style

Prefer simple calls such as fill(...), strokeWidth(...), and fontSize(...) to set the drawing state:

fill(255, 0, 0)
stroke(255)
strokeWidth(5)
ellipse(WIDTH/2, HEIGHT/2, 100, 100)

These functions need no style. prefix. Use the style module for additional settings, saving and restoring the drawing state, or chaining several commands together:

-- Draw a red ellipse with a 5px white stroke
style.push().fill(color.red).stroke(color.white).strokeWidth(5)
ellipse(WIDTH/2, HEIGHT/2, 100, 100)
style.pop()

See Style for the complete reference.

Anywhere a color is used as a parameter, you can use the following forms:

fill(r, g, b, a) -- separate color components in the range 0-255
fill(r, g, b) -- only red, green, blue color components with alpha assumed to be 255
fill(grey, alpha) -- only greyscale and alpha
fill(grey) -- only grayscale with alpha assumed to be 255
fill(color) -- a color object

Matrix

Use matrix to move, rotate, and scale your drawings. Its view and projection matrices control where the camera looks and how a 3D scene appears on screen. You can also use a camera to manage these settings.

Matrix commands can be chained too. Use push() to save the current matrices and pop() to restore them after drawing:

-- Translate then rotate in one expression
matrix.push().translate(100, 100).rotate(45)
rect(0, 0, 50, 50)
matrix.pop()

See Matrix for a complete reference

3D Drawing

To draw in 3D, switch from the default 2D orthographic projection to a perspective projection using matrix.perspective(). Always wrap 3D drawing in a matrix.push() / matrix.pop() pair so the 2D projection is restored afterwards.

Important

With matrix.perspective(), the camera sits at the origin and looks toward +Z. Objects must have a positive Z coordinate to be visible. Use matrix.translate() to move objects in front of the camera.

function draw()
    background(20, 20, 30)

    -- All 3D drawing goes inside a matrix.push/pop block
    matrix.push()
        matrix.perspective(60)          -- 60° field of view
        matrix.translate(0, 0, 5)       -- move object 5 units forward (+Z)
        matrix.rotate(angle, 0, 1, 0)   -- spin around Y axis
        myMesh:draw()
    matrix.pop()

    -- 2D drawing after matrix.pop() uses the default screen projection
    text("Hello", WIDTH/2, 40)
end

To position the camera elsewhere in the scene, set a custom view matrix using matrix.view() together with mat4.orbit():

matrix.push()
    matrix.perspective(60)
    -- Orbit camera: looking at origin from distance 8, tilted 20° up and 45° around Y
    matrix.view(mat4.orbit(vec3(0, 0, 0), 8, 20, 45))
    myMesh:draw()
matrix.pop()

Background

background() clears the screen each frame with a solid color (or image/shader):

background(0, 0, 0)        -- black
background(40, 40, 50)     -- dark blue-grey
background(color.white)    -- using a color object

See Drawing Commands for full documentation

Vector Drawing

Draw lines and shapes using the current Style settings:

-- Lines
style.push().stroke(255, 0, 0).strokeWidth(4)
line(100, 100, 400, 300)
style.pop()

-- Shapes
style.push().fill(0, 128, 255).stroke(255).strokeWidth(2)
rect(WIDTH/2, HEIGHT/2, 200, 100)       -- centered rectangle
ellipse(WIDTH/2, HEIGHT/2, 150, 150)    -- circle
style.pop()

-- Polygon
style.push().fill(255, 200, 0)
polygon(200,100, 300,200, 250,300, 150,300, 100,200)
style.pop()

See Drawing Commands for a complete list of vector drawing functions

Text

Draw text on the screen with text(), followed by its horizontal and vertical position. Put the call in draw() so the message appears every frame:

function draw()
    background(30)
    text("Hello, Codea!", WIDTH/2, HEIGHT/2)
end

The bottom-left corner of the screen is (0, 0). Increase x to move text to the right, or y to move it up. WIDTH/2, HEIGHT/2 is the center of the screen.

Size, color, and font

Set these before drawing your text. The following examples belong inside draw() too:

fontSize(40)
fill(255, 210, 80)
font("Arial-BoldMT")
text("You win! 🎉", WIDTH/2, HEIGHT/2)

Use fontSize to control the size in points, fill to set the color, and font to choose a font face.

Positioning and multiple lines

Use shapeMode to choose which part of a message sits at the coordinates you give to text. CORNER places the lower-left corner there, which is handy for a score near the edge of the screen:

fontSize(32)
shapeMode(CORNER)
text("Score: 120", 40, 40)

CENTER places the center of the whole message at that point:

shapeMode(CENTER)
text("Level complete!", WIDTH/2, HEIGHT/2)

Line alignment is independent of the block anchor. For a centered block with left-aligned lines:

shapeMode(CENTER)
textAlign(LEFT)
text("Level complete!\nTap to continue", WIDTH/2, HEIGHT/2)

textAlign and style.textAlign have identical behavior. Alignment and wrapping calls can be made in any order without changing the block anchor.

Use \n to start a new line. For a longer message, pass a width to text() to wrap it:

shapeMode(CORNER)
text("Explore the island and find three hidden keys before sunset.",
     40, HEIGHT/2, WIDTH - 80)

You can also supply a height to align text within a box. See textAlign() for alignment within the box, and shapeMode() for positioning the box.

Measuring text

Use textSize() when you need to leave room for a label or place another message below it. Set the font and size before measuring, just as you would before drawing:

fontSize(32)
shapeMode(CENTER)
textAlign(CENTER | MIDDLE)
local message = "Score: 120"
local width, height = textSize(message)
text(message, WIDTH/2, HEIGHT/2)
text("Best: 200", WIDTH/2, HEIGHT/2 - height - 12)

For wrapped text, pass the same width to textSize and text.

To align different fonts along the same baseline, use font.metrics(). It returns measurements such as ascent, descent, and capital-letter height for the current font and size. These describe the font rather than a particular message.

Making text stand out

A shadow helps a label remain readable over a busy background:

fontSize(40)
fill(255)
style.textShadow(color(0, 0, 0, 180), vec2(2, -2), 3)
text("Ready?", WIDTH/2, HEIGHT/2)

The color controls its tint and opacity, offset moves it relative to the text, and radius controls the blur. A radius of zero gives a sharp shadow. Use style.noTextShadow() to turn the shadow off. To change the appearance of just one label, surround its settings and drawing calls with style.push() and style.pop(). That restores the settings used by the rest of your drawing. Text settings reset each frame, so keep them inside draw().

Formatting parts of a message

Tags let you make individual words bold, italic, or a different color. You must use the atlas text renderer by calling style.textRenderer(style.atlas) before drawing tagged text:

style.push()
style.textRenderer(style.atlas)
fontSize(32)
text('Find the <b>key</b> to open the <fill color="red">red door</fill>.',
     WIDTH/2, HEIGHT/2)
style.pop()

<b>...</b> makes a span bold, <i>...</i> makes it italic, and <fill color="red">...</fill> changes its color. Close each tag after the words it should affect. Atlas text also supports decorations such as underlines:

style.push()
style.textRenderer(style.atlas)
style.textUnderline(255)
text("Next chapter", WIDTH/2, HEIGHT/2)
style.pop()

A decoration’s color enables it; set its alpha to zero to turn it off, for example style.textUnderline(255, 0).

Animating letters

When using atlas text, you can define your own tags for effects such as waving letters. Register the tag in setup(), then use it in the text you draw:

function setup()
    text.style.wave = function(tag, format)
        format.callback = function(str, index, letter)
            letter.offsetY = math.sin(time.elapsed * 5 + index) * 6
        end
    end
end

function draw()
    background(30)
    fontSize(40)
    style.textRenderer(style.atlas)
    text("<wave>Hello!</wave>", WIDTH/2, HEIGHT/2)
end

The callback adjusts each letter’s position. You can also change its color or opacity. See text.style for custom tags and glyphModifier for the per-letter controls.

Choosing native or atlas text

Most labels, scores, paragraphs, and emoji can use the default, style.native. Choose style.atlas when you want tags, underlines, or animated-letter effects. Atlas text does not support color emoji, so keep emoji labels on native rendering.

Use style.textRenderer(style.native) to switch back. You can mix both in a frame; style.push() and style.pop() are useful for keeping each label’s settings local. Remember that your style and renderer choices apply to textSize, so measure and draw with the same settings.

See Style for individual text settings and Drawing Commands for drawing, measurement, and custom effects.

Images and Sprites

Images are loaded with image.read() and drawn with sprite():

function setup()
    img = image.read(asset.builtin.Blocks.Brick)
end

function draw()
    background(0)
    sprite(img, WIDTH/2, HEIGHT/2, 200, 200)
end

Context

The context module lets you draw into an image instead of the screen, using context.push() and context.pop():

local target = image(512, 512)

context.push(target)
    background(0)
    style.push().fill(255, 0, 0)
    ellipse(256, 256, 200, 200)
    style.pop()
context.pop()

-- Now draw that image to screen
sprite(target, WIDTH/2, HEIGHT/2)

Meshes

Use a mesh to draw 3D objects or custom 2D shapes. Start with a built-in shape or define your own vertices.

Built-in mesh generators

sphereMesh   = mesh.sphere(1)          -- sphere, radius 1
boxMesh      = mesh.box(vec3(1,1,1))   -- box, 1×1×1
cylinderMesh = mesh.cylinder(0.5, 1)   -- radius 0.5, height 1
torusMesh    = mesh.torus(0.25, 1)     -- torus

Drawing a mesh in 3D

function setup()
    sphereMesh = mesh.sphere(1)
    angle = 0
end

function draw()
    background(20, 20, 30)
    angle = angle + 0.5

    matrix.push()
        matrix.perspective(60)
        matrix.translate(0, 0, 4)
        matrix.rotate(angle, 0, 1, 0)
        sphereMesh:draw()
    matrix.pop()
end

Building a mesh from vertices

Set mesh.vertices to draw a triangle for each group of three vertices. This also creates the indices that connect them. Use mesh.positions when changing an existing shape while keeping its triangle connections:

-- Each group of three vertices forms a triangle
m = mesh()
m.vertices = { vec3(0,0,0), vec3(1,0,0), vec3(0.5,1,0) }  -- one triangle
m.colors   = { color(255,0,0), color(0,255,0), color(0,0,255) }
m:draw()

-- Use positions only to deform an existing mesh (preserves its index buffer)
sph = mesh.sphere(1)
-- modify sph.positions each frame to animate without breaking sphere indices

Complete example: Rotating RGB Cube

Example

-- RGB Cube
-- A rotating cube with RGB vertex colors

function setup()
    viewer.mode = FULLSCREEN

    -- Build a cube mesh with 8 corners
    cubeMesh = mesh()
    local s = 0.5

    local v = {
        vec3(-s,-s,-s), vec3( s,-s,-s), vec3( s, s,-s), vec3(-s, s,-s),
        vec3(-s,-s, s), vec3( s,-s, s), vec3( s, s, s), vec3(-s, s, s),
    }

    -- Map each corner's position to an RGB color
    local function posToColor(p)
        return color(
            math.floor((p.x + s) / (2*s) * 255),
            math.floor((p.y + s) / (2*s) * 255),
            math.floor((p.z + s) / (2*s) * 255))
    end

    -- 6 faces × 2 triangles, wound for correct front-face culling
    local faces = {
        {v[5],v[6],v[7]}, {v[5],v[7],v[8]}, -- Front  (+z)
        {v[2],v[1],v[4]}, {v[2],v[4],v[3]}, -- Back   (-z)
        {v[1],v[5],v[8]}, {v[1],v[8],v[4]}, -- Left   (-x)
        {v[6],v[2],v[3]}, {v[6],v[3],v[7]}, -- Right  (+x)
        {v[8],v[7],v[3]}, {v[8],v[3],v[4]}, -- Top    (+y)
        {v[1],v[2],v[6]}, {v[1],v[6],v[5]}, -- Bottom (-y)
    }

    local verts, cols = {}, {}
    for _, tri in ipairs(faces) do
        for _, p in ipairs(tri) do
            table.insert(verts, p)
            table.insert(cols, posToColor(p))
        end
    end

    -- Use 'vertices' (not 'positions') so indices are set automatically
    cubeMesh.vertices = verts
    cubeMesh.colors   = cols

    angleX, angleY = 0, 0
end

function draw()
    background(20, 20, 30)

    angleX = angleX + 0.4
    angleY = angleY + 0.6

    -- Set up perspective projection.
    -- With matrix.perspective() the camera is at the origin looking
    -- toward +Z, so objects must have a positive Z to be visible.
    matrix.push()
        matrix.perspective(60)
        matrix.translate(0, 0, 3)      -- place cube 3 units in front
        matrix.rotate(angleX, 1, 0, 0)
        matrix.rotate(angleY, 0, 1, 0)
        cubeMesh:draw()
    matrix.pop()
end

Shaders and Materials

Both shaders and materials can be applied to a mesh to control how it is rendered. See Shaders, Materials and Shaders and Materials for details.

Lighting

Codea supports dynamic lighting via Lights. Generated meshes (mesh.sphere(), mesh.box(), etc.) use a lit material by default, so without any lights they render black. There are two ways to make them visible:

Option 1: Unlit material with a color (no light needed):

sph = mesh.sphere(1)
sph.material = material.unlit()
sph.material.color = color(100, 180, 255)

Option 2: Lit material with a directional light (produces 3D shading):

function setup()
    sph = mesh.sphere(1)
    sph.material = material.lit()
    sph.material.color = color(100, 180, 255)

    dirLight = light.directional(vec3(1, -1, 1))
    dirLight.intensity = 2
end

function draw()
    background(20, 20, 30)
    matrix.push()
        matrix.perspective(60)
        light.push(dirLight)
        matrix.translate(0, 0, 4)
        sph:draw()
        light.pop()
    matrix.pop()
end

Note

When drawing meshes directly, only light.directional() is supported. Point and spot lights are not supported for this kind of drawing.

Full sphere example

-- 3D Sphere with directional light

function setup()
    viewer.mode = FULLSCREEN
    sphereMesh = mesh.sphere(1)
    sphereMesh.material = material.lit()
    sphereMesh.material.color = color(100, 180, 255)

    dirLight = light.directional(vec3(1, -1, 1))
    dirLight.intensity = 2

    angle = 0
end

function draw()
    background(20, 20, 30)
    angle = angle + 0.5

    matrix.push()
        matrix.perspective(60)
        light.push(dirLight)
        matrix.translate(0, 0, 4)
        matrix.rotate(angle, 0, 1, 0)
        sphereMesh:draw()
        light.pop()
    matrix.pop()
end

Drawing shapes and changing style

Each row draws a shape with its default style, a colored fill, and a white outline. style.reset() restores the defaults. Try changing the last four rect() arguments to round each corner differently.

-- Learn to Codea
-- Drawn in Code

function setup()
end

-- Codea calls the draw() function every frame to redraw the screen
-- This could be as much as 60 or 120 times per second, or less if
-- you demand too much from the CPU/GPU

-- Put drawing commands in here to draw the various doodads you want
function draw()

    -- Some background on the background(r,g,b,a) command
    -- This command clears the screen with the specified color. The parameters
    -- represent the amount of each primary color component to use (i.e. red, green, blue)
    -- When called all previous things drawn on the screen will be cleared with the color used
    background(25, 25, 25)

    -- 2D Vector Drawing

    -- For based 2D drawing jobs we can use the following commands:
    -- ellipse(x, y, w, h)
    -- rect(x, y, w, h)
    -- rect(x, y, w, h, radius)
    -- line(x1, y1, x2, y2)
    -- polygon(p1, p2, p3, p4...)
    -- shape(x, y, closed, func)

    -- ellipse() draws an ellipse (no kidding?) at the specified x, y location
    -- The x, y values are euclidian coordinates (i.e. horizontal and vertical) with the
    -- origin starting at 0, 0 (bottom left of the screen)
    -- Lets draw one:
    ellipse(WIDTH/2 - 120, HEIGHT/2 + 120, 100, 100)

    -- You may have noticed the all-caps constant WIDTH and HEIGHT
    -- These handily give us the current resolution of the screen in sort-of pixels
    -- (this is a retina screen thing, don't worry for now)
    -- By using WIDTH/2 and HEIGHT/2 I get the exact center of the screen regardless of how
    -- big it happens to be

    -- Style

    -- To control the things like colors and strokes for shapes we use Codea's style commands
    -- You can just do:

    fill(255, 0, 0) -- make shapes fill with red
    ellipse(WIDTH/2, HEIGHT/2 + 120, 100, 100)

    -- Make shapes have a white stroke with 5 pixel width
    -- We can also chain together multiple style commands
    style.stroke(255).strokeWidth(5)
    ellipse(WIDTH/2 + 120, HEIGHT/2 + 120, 100, 100)

    -- We can also reset the style to it's default state
    style.reset().rectMode(CENTER)

    -- We can also draw a rectangle
    -- rectMode(CENTER) makes these positions the centers of the rectangles
    rect(WIDTH/2 - 120, HEIGHT/2, 100, 100)

    fill(255, 0, 0)
    rect(WIDTH/2, HEIGHT/2, 100, 100)

    style.stroke(255).strokeWidth(5)
    rect(WIDTH/2 + 120, HEIGHT/2, 100, 100)


    style.reset().rectMode(CENTER)

    -- Rounded rectangles are possible too!
    -- Extra 1 parameter to round all corners
    rect(WIDTH/2 - 120, HEIGHT/2 - 120, 100, 100, 5)

    fill(255, 0, 0)
    rect(WIDTH/2, HEIGHT/2 - 120, 100, 100, 10)

    -- Extra 4 parameters to vary how much each corner is rounded
    style.stroke(255).strokeWidth(5)
    rect(WIDTH/2 + 120, HEIGHT/2 - 120, 100, 100, 5, 10, 5, 15)
end

function touched(touch)
end

Building an orbit with nested transforms

Satellites orbit a moving center while moons orbit each satellite. Each matrix.push() is paired with matrix.pop(), so moving one moon does not move the next satellite. Try changing the orbit radii or the number of moons.

-- Learn to Codea
-- The Matrix

function setup()
end

function draw()

    background(25, 25, 25)

    local r = time.elapsed * 15

    -- The matrix module gives you control over positioning of drawing commands

    -- By changing the current matrix, this changes where drawing occurs

    -- The easiest way to think of this is that the current matrix represents
    -- the origin of the screen
    -- matrix.translate(WIDTH/2, HEIGHT/2) - move drawing to the middle of the screen

    -- You can also rotate and scale drawing
    -- Transforming the matrix combines with any previous transformation
    -- i.e. matrix.translate(WIDTH/2, HEIGHT/2).translate(100, 100)
    -- Drawing will now originate 100 pixels up and to the right of the middle of the screen

    -- You can also use matrix.push()/pop() to save and load the current matrix transform
    -- similar to how style.push()/pop() is used

    -- matrix.transform2d()/transform3d() allows you to apply full transformations in one
    -- command for convenience

    -- If you need to clear all current transformations you can use matrix.reset()

    -- You can also create a mat4 (4x4 matrix) type and use this with matrix.get()/set()

    -- There are additional commands for adjusting view and projection matrices
    -- matrix.ortho() - use orthographic (2D) projection
    -- matrix.perspective() - use perspective (3D) projection
    -- matrix.projection(m) - use a custom projection matrix
    -- matrix.view(m) - use a custom view matrix

    -- Move the origin to the center of the screen and rotate over time
    matrix.transform2d(WIDTH/2, HEIGHT/2, 1, 1, r)
    ellipse(0, 0, 50)

    -- Draw 6 satellites that orbit and rotate the center
    for i = 1, 6 do
        -- Accumulate rotations
        matrix.rotate(360/6)

        -- Use additional push and transform to create a recursive hierarchy
        matrix.push().transform2d(math.min(WIDTH, HEIGHT) * 0.28, 0, 1, 1, r * 1.25)
        ellipse(0, 0, 25)

        -- Additional mini satellites that orbit the current origin
        for i = 1, 6 do
            matrix.rotate(360/6)
            matrix.push().transform2d(math.min(WIDTH, HEIGHT) * 0.075, 0)
            ellipse(0, 0, 15)
            matrix.pop()
        end

        -- Pop here is crucial to let the next satellite transform relative to its parent
        matrix.pop()
    end

end

function touched(touch)
end

Comparing blend modes

Choose a blend mode or change either color in Controls to see how overlapping colors combine. Drawing order matters: the second circle blends over the first. The images below the circles show how blending works with pictures.

function setup()
    parameter.color("ColorA", color(225, 138, 130))
    parameter.color("ColorB", color(169, 255, 129))

    blendModes =
    {
        "NORMAL",
        "ADDITIVE",
        "MULTIPLY",
        "SCREEN",
        "LIGHTEN",
        "LINEAR_BURN",
        "PREMULTIPLIED",
        "DISABLED"
    }

    parameter.option("Blend", blendModes)

    alpha1 = image.read(asset.Alpha1)
    alpha2 = image.read(asset.Alpha2)
end

function draw()
    background(64)

    matrix.push().translate(WIDTH/2, HEIGHT/2 + 130)

    style.reset()
    style.blend(_G[blendModes[Blend]])
    fill(ColorA)
    ellipse(-50, 0, 160)
    fill(ColorB)
    ellipse(50, 0, 160)

    matrix.translate(0, -220)

    style.reset().blendFunc(EQUATION_MAX)
    sprite(alpha1, -50, 0, 160)
    sprite(alpha2, 50, 0, 160)

    matrix.pop()
end

function touched(touch)
end

Saving and restoring styles

These swatches share three saved styles: foreground, background, and label. style.get() saves the settings and style.set() restores them. Change one saved style to update every swatch.

function setup()

    -- Here are some built-in colors that come with codea!
    colors =
    {
        color.black,
        color.white,
        color.clear,
        color.cyan,
        color.gray,
        color.red,
        color.green,
        color.blue,
        color.magenta,
        color.yellow
    }

    swatchFG = style.reset().rectMode(CENTER).stroke(255).strokeWidth(3).get()
    swatchBG = style.reset().rectMode(CENTER).noStroke().fill(90).get()
    label = style.reset().fontSize(14).textAlign(CENTER).fill(200).get()

end

local colorNames = {"black", "white", "clear", "cyan", "gray", "red", "green", "blue", "magenta", "yellow"}
local SWATCH_SIZE = 100
local SWATCH_SPACING = 15

function swatch(x, y, ...)
    style.set(swatchBG)
    rect(x + 5, y - 5, SWATCH_SIZE, SWATCH_SIZE, 10)
    style.set(swatchFG).fill(...)
    rect(x, y, SWATCH_SIZE, SWATCH_SIZE, 10)
end

function draw()
    background(32)

    local columns = math.max(1, math.floor(WIDTH / (SWATCH_SIZE + SWATCH_SPACING)))
    local rows = math.ceil(#colors / columns)
    for k, v in ipairs(colors) do
        local column, row = (k - 1) % columns, math.floor((k - 1) / columns)
        matrix.push().translate((column + 0.5) * WIDTH / columns,
            HEIGHT/2 + (rows/2 - row - 0.5) * 150)
        swatch(0, 0, v)
        style.set(label)
        text(colorNames[k], 0, -SWATCH_SIZE/2 - 20)
        matrix.pop()
    end

end

function touched(touch)
end

Interpolating vertex colors

Three vertices define a triangle, with a color at each corner. Codea blends these colors across its surface. Change its size in Controls and watch it rotate.

-- Mesh Example
-- Author: John Millard


function setup()
    print("Hello Mesh!")

    -- Here we create a mesh, just a single triangle
    parameter.integer("triSize", 10, 300, 100)

    -- Create a new empty mesh
    triMesh = mesh()

    -- This is an array of colours we'll assign to the triMesh vertices
    triCol = { color(255, 0, 0, 255),
    color(255, 255, 0, 255),
    color(0, 100, 255, 255)}

    -- Assign colors to the mesh, there must be the same number of colours as vertices
    triMesh.colors = triCol
end

-- This function gets called once every frame
function draw()
    -- Dark background color
    background(20, 20, 40)

    -- Save the current transform (translation, rotation and scale)
    matrix.push()

    -- Translate coordinates to the middle of the screen
    matrix.translate(WIDTH/2, HEIGHT/2)

    -- Rotate the transform at 100 degrees per second
    matrix.rotate(time.elapsed*100)

    -- Construct equilateral triangle points, this could be any 3 points
    local top = vec2(math.cos(2*math.pi/6), math.sin(2*math.pi/6))
    top = top * triSize

    local left = vec2(math.cos(6*math.pi/6), math.sin(6*math.pi/6))
    left = left * triSize

    local right = vec2(math.cos(10*math.pi/6), math.sin(10*math.pi/6))
    right = right * triSize

    -- Set points on mesh, every 3 points constructs a new triangle
    triMesh.vertices = { top,
                         left,
                         right }

    -- Draw the mesh that we setup
    triMesh:draw()

    -- Restore the previous transform
    -- This is useful if you need to position multiple objects differently
    matrix.pop()
end

Turning a polygon into triangles

Tap around an outline without crossing its edges. mesh.triangulate() divides the polygon into triangles so it can be drawn as a filled shape.

-- Mesh 2 - Triangulate Example
-- Author: John Millard

function setup()
    print("Hello Triangulate!")

    msh = mesh()
    points = {}
    colors = {}
end

function updateMesh()
    if #points >= 3 then
        msh.positions = points
        msh.colors = colors
        msh.indices = mesh.triangulate(points)
    end
end

-- This function gets called once every frame
function draw()
    -- Dark background color
    background(20, 20, 40)
    msh:draw()

    style.noStroke().fill(255)
    for k, v in pairs(points) do
        ellipse(v, 10)
    end
end

function touched(touch)
    if touch.state == ENDED and touch.tapCount == 1 then
        table.insert(points, touch.pos)
        table.insert(colors, color(touch.x / WIDTH * 255, touch.y / HEIGHT * 255, 128))
        updateMesh()
    end
end

Assets are files such as images, sounds, shaders, and 3D models. Drawing a sprite starts with choosing an image. Type sprite() and tap its highlighted parentheses to open the asset picker, then choose an image. Codea inserts an asset key, such as asset.builtin.Planet_Cute.Character_Boy.

An asset key identifies a file or folder; it is not the image data itself. Codea can check named assets and offer autocomplete while you write code. Start typing asset. to explore the available files and folders.

function draw()
    background(40)
    sprite(asset.builtin.Planet_Cute.Character_Boy, WIDTH/2, HEIGHT/2, 120)
end

Asset locations

- asset.MyImage refers to a file in your project. - asset.documents.MyImage refers to a file in Codea’s Documents folder. - asset.icloud.MyImage refers to a file in Codea’s iCloud documents. - asset.builtin.Planet_Cute.Character_Boy refers to a built-in asset pack. - asset.current refers to the project whose code is executing, including when that code belongs to a dependency. Use it for a library’s own resources. - asset.ExternalFolderName.MyImage refers to a folder reference added with the asset picker.

Loading and drawing

Pass an image asset directly to sprite(), or load it once with image.read() and keep the resulting image. The latter is useful when you also want to inspect or edit its pixels. See sound.read() and mesh.read() for other asset types.

function setup()
    character = image.read(asset.builtin.Planet_Cute.Character_Boy)
end

function draw()
    background(40)
    tint(255, 200, 200)
    sprite(character, WIDTH/2, HEIGHT/2, 120)
    style.noTint()
end

Paths and filenames

Use the concatenation operator .. to build a path dynamically or identify a file that does not exist yet. For example, save an image with image.save(asset.documents .. "Picture.png", character).

Square brackets preserve the exact filename, including spaces, punctuation, and extensions: asset.documents["My File (2).png"]. Unlike a named asset key, this lookup cannot be checked or autocompleted ahead of time.

When two files have the same name but different extensions, autocomplete uses an extension suffix to distinguish them. For example, asset.MyObject_png and asset.MyObject_obj identify MyObject.png and MyObject.obj.

Listing assets and tracking changes

Use # on an asset library to count its entries, and .all to obtain an array of asset keys. This works for the project, Documents, or a nested folder.

print("Project files:", #asset)
for i, key in ipairs(asset.all) do
    print(i, key.path)
end

Assign a function to a folder’s updated property to be notified when its contents change. This applies to folders, not individual files.

asset.updated = function(library)
    print("Project files changed:", #library)
end

See Assets and File Operations for more about storing and managing project resources.