API Reference - Tiny Game Engine

Iterate over values of a table. - If you want to iterate over keys, use `pairs(table)`. - If you want to iterate over index, use `ipairs(table)`. - If you want to iterate in reverse, use `rpairs(table)`.

Parameters

table table

Append *all values* from the table `source` to the table `dest`.

Parameters

source table

dest table

function _draw()
    gfx.cls()
    local src = {1, 2, 3}
    local dst = {4, 5}
    local result = append(src, dst)
    for k,v in ipairs(result) do
        print(v, (k + 1) * 8, 8) 
    end
end

Add *all key/value* from the table `source` to the table `dest`.

Parameters

source table

dest table

function _draw()
    gfx.cls()
    local src = {x = 1, y = 2, z = 3}
    local dst = {a = 4, b = 5}
    local result = merge(src, dst)
    local index = 1
    for k,v in pairs(result) do
        print(k..":"..v , index * 4 * 8, 8)
        index = index + 1
    end
end

Create new instance of a class by creating a new table and setting the metatable. It allow to create kind of Object Oriented Programming.

Parameters

class table

default table

local Player = {
    x = 128,
    y = 128,
    color = 8
}

function Player:draw()
    shape.rectf(self.x, self.y, 10, 10, self.color)
end

function _init()
    -- create a new player
    player = new(Player)
    -- create a new player with default vaules
    player2 = new(Player, {x = 200, y = 200, color = 9})
end

function _draw()
    gfx.cls()
    player:draw() -- call the draw method on the player instance.
    player2:draw() -- call the draw method on the player2 instance.
end

Print on the screen a string. Default color is the closest to white (#FFFFFF) in the palette. To ensure visibility, use a color that contrasts with the cls() background color.

Parameters

str string

x number

y number

color number

function _draw()
    gfx.cls()
    -- every character is a sprite 4x4 pixels.
    print("hello")
    print("world", 10, 8)
    print("how", 10, 16, 4)
    print("are", 28, 16, 5)
    print("you", 46, 16, 6)
    print("...", 64, 16, math.rnd(10))
end

Iterate over values of a table in reverse order. The iterator return an index and the value. The method is useful to remove elements from a table while iterating on it.

Parameters

table table

function _draw()
    gfx.cls()
    local data = {
        { name = "riri" },
        { name = "fifi" },
        { name = "loulou" }
    }

    local y = 0
    for index, key in rpairs(data) do
        print(index .. " - " .. key.name, 10, y)
        y = y + 10
    end
end

Log a message into the console.

Parameters

str any

function _update()
    console.log("hello from the console")
    console.log("Log a value: ", tiny.frame)
    console.log("Log a table: ", ctrl.touch())
end
  
function _draw()
    gfx.cls()
    -- draw the mouse position.
    local pos = ctrl.touch()

    shape.line(pos.x - 2, pos.y, pos.x + 2, pos.y, 3)
    shape.line(pos.x, pos.y - 2, pos.x, pos.y + 2, 3) 
end

Return true if the key was pressed during the last frame. When called without argument, return a table of all keys pressed during the last frame (values matching the keys lib), or false if no key was pressed. If you need to check that the key is still pressed, see `ctrl.pressing` instead.

Parameters

key number

local percent_a = 1
local percent_b = 1

function _update()
    percent_a = math.min(percent_a + 0.05, 1)
    percent_b = math.min(percent_b + 0.05, 1)

    if ctrl.pressed(keys.space) then
        percent_a = 0
    end
    
    if ctrl.pressing(keys.space) then
        percent_b = 0
    end

    local offset_a = juice.powIn2(0, 8, percent_a)
    local offset_b = juice.powIn2(0, 8, percent_b)

    gfx.cls()
    shape.rectf(64, 128 - 16, 32, 32, 7)
    shape.rectf(64, 128 - 32 + offset_a, 32, 32, 8)

    shape.rectf(32 + 128, 128 - 16, 32, 32, 7)
    shape.rectf(32 + 128, 128 - 32 + offset_b, 32, 32, 8)

    print("pressed", 64, 128 + 32)
    print("pressing", 32 + 128, 128 + 32)
end

Return true if the key is still pressed.

Parameters

key number

local percent_a = 1
local percent_b = 1

function _update()
    percent_a = math.min(percent_a + 0.05, 1)
    percent_b = math.min(percent_b + 0.05, 1)

    if ctrl.pressed(keys.space) then
        percent_a = 0
    end
    
    if ctrl.pressing(keys.space) then
        percent_b = 0
    end

    local offset_a = juice.powIn2(0, 8, percent_a)
    local offset_b = juice.powIn2(0, 8, percent_b)

    gfx.cls()
    shape.rectf(64, 128 - 16, 32, 32, 7)
    shape.rectf(64, 128 - 32 + offset_a, 32, 32, 8)

    shape.rectf(32 + 128, 128 - 16, 32, 32, 7)
    shape.rectf(32 + 128, 128 - 32 + offset_b, 32, 32, 8)

    print("pressed", 64, 128 + 32)
    print("pressing", 32 + 128, 128 + 32)
end

Get coordinates of the current touch/mouse. If the mouse/touch is out-of the screen, the coordinates will be the last mouse position/touch. The function return those coordinates as a table {x, y}. A sprite can be draw directly on the mouse position by passing the sprite number.

Parameters

sprN number

function _draw()
  gfx.cls(2)
  p = ctrl.touch()
  print("coordinates: "..p.x .. "x"..p.y, 1, 1, 4)
  shape.rectf(p.x, p.y, 5,5, p.x + p.y)
end

Return the position of the touch (as `{x, y}`)if the screen was touched or the mouse button was pressed during the last frame. `nil` otherwise. The touch can be : - 0: left click or one finger - 1: right click or two fingers - 2: middle click or three fingers If you need to check that the touch/mouse button is still active, see `ctrl.touching` instead.

Parameters

touch number

local circles = {}

function _update()
    local pos = ctrl.touched(0)
    if pos ~= nil then
        table.insert(circles, pos)
    end
end

function _draw()
    gfx.cls()
    local p = ctrl.touch()
    shape.circlef(p.x, p.y, 4, 8)
    for pos in all(circles) do 
        shape.circlef(pos.x, pos.y, 4, 9)
        print("("..pos.x .. ", "..pos.y..")", pos.x + 3, pos.y + 3)
    end
end

Return the position of the touch (as `{x, y}`)if the screen is still touched or the mouse button is still pressed. `nil` otherwise. The touch can be : - 0: left click or one finger - 1: right click or two fingers - 2: middle click or three fingers

Parameters

touch number

function _draw()
    gfx.cls()
    local p = ctrl.touch()
    shape.circlef(p.x, p.y, 4, 8)

    local start = ctrl.touching(0)
    if start ~= nil then
        local pos = ctrl.touch()
        shape.line(start.x, start.y, pos.x, pos.y, 1)
        print("("..start.x .. ", "..start.y..")", start.x, start.y)
        print("("..pos.x .. ", "..pos.y..")", pos.x, pos.y)
    end
end

Load and get the content of the file name

Parameters

name string

Save the content into a local file, on desktop or in the local storage on the web platform.

Parameters

name string

content any

Move the game camera.

Parameters

x number

y number

local x = 0
local y = 0

function _update()
    if ctrl.pressing(keys.left) then
        x = x - 0.5
    elseif ctrl.pressing(keys.right) then
        x = x + 0.5
    end

    if ctrl.pressing(keys.up) then
        y = y - 0.5
    elseif ctrl.pressing(keys.down) then
        y = y + 0.5
    end
    gfx.camera(math.floor(x), math.floor(y))
end

function _draw()
    gfx.cls(2)
    for x = 0 - 64, 256 + 64, 16 do
        for y = 0 - 64, 256 + 64, 16 do
            shape.line(x - 2, y, x + 2, y, 9)
            shape.line(x, y - 2, x, y + 2, 9)
        end
    end
    print("camera: ("..x..", "..y..")", 6, 6)
    
    shape.rect(0, 0, 256, 256, 1)
end

Clip the draw surface (ie: limit the drawing area).

Parameters

x number

y number

width number

height number

function _init()
  c = {}
  for i=1,100 do
    table.insert(c, {x=math.rnd(256), y=math.rnd(256), c = math.rnd(1,12)})
end

end
function _draw()
  gfx.cls()
  local pos = ctrl.touch()
  -- set a clip area to crop circles
  gfx.clip(pos.x - 20, pos.y - 20, 40, 40)
  for circle in all(c) do
    shape.circlef(circle.x, circle.y, 10, circle.c)
  end
end

Clear the screen. When called without arguments, clears with the color closest to black (#000000) in the palette. To ensure visibility, always draw with a color index DIFFERENT from the cls() color.

Parameters

color number

function _draw()
    if ctrl.pressed(keys.space) then
       gfx.cls()
    end

    print("Press space to clear the screen") 
    local pos = ctrl.touch()
    shape.circlef(pos.x, pos.y, 4, math.rnd())
end

Apply a dithering pattern on every new draw call. The pattern is using the bits value of a 2 octet value. The first bits is the one on the far left and represent the pixel of the top left of a 4x4 matrix. The last bit is the pixel from the bottom right of this matrix.

Parameters

pattern number Dither pattern. For example: 0xA5A5 or 0x3030

function _draw()
    gfx.cls()
    gfx.dither()
    shape.circlef(30, 30, 30, 2)
    gfx.dither(0xA5A5) -- set a dithering pattern
    shape.circlef(50, 50, 30, 3)
    gfx.dither(0x0842) -- set another dithering pattern
    shape.circlef(70, 70, 30, 2)
end

Switch to another draw mode. - 0: default. - 1: drawing with transparent (ie: can erase part of the screen) - 2: drawing a stencil that will be use with the next mode - 3: drawing using a stencil test (ie: drawing only in the stencil) - 4: drawing using a stencil test (ie: drawing everywhere except in the stencil)

Parameters

mode number

local draw_stencil = 2
local draw_inside_stencil = 3
local draw_outside_stencil = 4

local outside = false

function _draw()
    if ctrl.pressed(keys.space) then
        outside = not outside
    end

    gfx.cls(3)

    gfx.draw_mode(draw_stencil)

    -- draw a circle in the middle of the screen
    shape.circlef(128, 128, 64, 1)
    
    if outside then
        gfx.draw_mode(draw_inside_stencil)
    else
        gfx.draw_mode(draw_outside_stencil)
    end
    
    -- draw the sprite sheet. only in the circle
    spr.sdraw()
    gfx.draw_mode()
end

Change a color from the palette to another color.

Parameters

a number

b number

function _draw()
    gfx.cls()
    print("example", 10, 10, 2) -- print using the color index 2
    gfx.pal(2, 3) -- switch the text color to another color
    print("example", 10, 20, 2) -- print using the color index 2
    gfx.pal() -- reset the palette
    print("example", 10, 30, 2) -- print using the color index 2
end

Get the color index at the coordinate (x,y).

Parameters

x number

y number

function _draw()
   gfx.cls()
   local index = 0
   for x=0, 240, 16 do
     for y=0, 240, 16 do
        shape.rectf(x, y, 16, 16, index)
        index = index + 1
     end
   end

   local pos = ctrl.touch()
   local color = gfx.pget(pos.x, pos.y)
   if color ~= nil then 
     shape.rectf(0, 0, 80, 6, 13)
     print("color index: "..color)
   end


   shape.circlef(pos.x - 2, pos.y - 2, 4, 0)
end

Set the color index at the coordinate (x,y).

Parameters

x number

y number

color number

function _draw()
   local pos = ctrl.touching(0)
   if pos ~= nil then
      -- set the pixel with the color 9 when the mouse is pressed
      local p = ctrl.touch()
      gfx.pset(p.x, p.y, 9)
   end
end

Transform the current frame buffer into a spritesheeet. - If the index of the spritesheet already exist, the spritesheet will be replaced - If the index of the spritesheet doesn't exist, a new spritesheet at this index will be created - If the index of the spritesheet is negative, a new spritesheet will be created at the last positive index.

Parameters

sheet any

function _draw()
    gfx.cls(1)
    -- draw a transparent circle (like a hole)
    shape.circlef(64, 128, 20, 0)
    -- keep the result as spritesheet 0
    gfx.to_sheet(0)

    gfx.cls(1)
    -- draw some circles
    shape.circlef(64, 108, 20, 8)
    shape.circlef(44, 128, 20, 9)
    shape.circlef(64, 148, 20, 10)
    shape.circlef(84, 128, 20, 11)

    -- draw over the circles
    -- the mask generated before.
    spr.sheet(0)
    spr.sdraw()
end

Parameters

start number

end number