API Reference

-- bob a sprite up and down
local x = 320 + sin(time() * 0.5) * 100

print(stat(0) .. "fps", 580, 469, 3)

local y = 240 + sin(time() * 0.3) * 80

local x = 320 + cos(time() * 0.3) * 80

-- aim from center toward mouse
local angle = atan2(my - 240, mx - 320)
local tx = 320 + cos(angle) * 40
local ty = 240 + sin(angle) * 40
line(320, 240, tx, ty, 7)

local x = rnd(640)   -- random x position
local slot = flr(rnd(8))  -- random int 0..7

local tile_x = flr(x / 16)

local rows = ceil(count / 8)

if abs(dx) < 4 then snap() end

x = max(0, x)        -- clamp to left edge
x = min(x, 624)     -- clamp to right edge

x = mid(0, x, 624)   -- keep x within screen

health = clamp(health + 10, 0, 100)

if btn("right") then x = x + 2 end

if btnp("z") then jump() end

local ax = joy_axis(0, 0) / 32768   -- normalise to -1..1
x = x + ax * 3

if joy_btn(0, 0) then fire() end

local h = joy_hat(0, 0)
if h & 1 ~= 0 then move_up() end

cls()     -- clear to black
cls(3)    -- clear to colour 3

camera(cam_x, cam_y)    -- scroll world
tilemap_draw(tm, 0, 0)
camera()                -- reset for HUD
print("100 pts", 4, 4, 7)

zoom(2)
spr(0, 160, 120)   -- draws at 32x32 pixels
zoom(1)

pset(320, 240, 7)   -- white pixel at center

local c = pget(mx, my)   -- sample colour under mouse

-- flash player red on hit, then restore
pal(7, 255, 0, 0)
spr(player_slot, px, py)
pal(7, 240, 240, 240)

pal_bank(1)         -- switch to bank 1's palette
local active = pal_bank()   -- 0 or 1

scene(0)              -- activate scene 0
local s = scene()     -- currently active scene, -1 if none

local slot = scene_import(0, 182)
if slot then
    -- use `slot` as the colour index when drawing in this scene, e.g.:
    -- rectfill(x, y, x+8, y+8, slot)
end

scene_save()   -- call once after building up your scenes with scene_import()

pset_batch({10,20,7, 11,20,7, 12,20,3})

local stars = {}
for i = 1, 80 do
  stars[i*2-1] = rnd(640)
  stars[i*2]   = rnd(480)
end

function _draw()
  pset_batch_xy(15, stars)   -- 80 stars, one C call
end

line(0, 0, 639, 479, 7)

rect(10, 10, 100, 50, 7)

rectfill(0, 460, 639, 479, 1)   -- HUD bar

circ(320, 240, 50, 7)

circfill(320, 240, 20, 8)   -- filled red circle

print("SCORE: " .. score, 8, 8, 7)
print("GAME OVER\npress Z", 260, 200, 8)

function _draw()
  fb_fade(3)       -- decay all pixels, skip cls()
  circfill(ox, oy, 6, 91)   -- bright dot leaves colour trail
end

spr(0, player.x, player.y)
spr(2, enemy.x, enemy.y, true, false)  -- flipped

local bullet_pos = {}

function _draw()
  -- fill bullet_pos with live positions...
  spr_batch(BULLET_SLOT, bullet_pos)
end

-- 2x2 tank from 4 bank slots (32x32 total)
local TANK = {0,0,0, 1,16,0, 2,0,16, 3,16,16}
spr_batch_composite(TANK, tank_positions)

spr_flag(GHOST_SLOT, "blend50")   -- always semi-transparent
spr_flag(GHOST_SLOT)              -- reset to normal

spr_alpha(SHIELD_SLOT, sx, sy, "blend50")

local px = {}
for i = 1, 16*16 do px[i] = 0 end
px[8*16+8+1] = 7   -- white dot at (8,8)
local dot = spr_new(16, 16, px)

spr_blit(dot, 320, 240)

local c = spr_get(0, 8, 8)

if hget(PLAYER, 8, 8) == 1 then -- center is collidable
end

if spr_is_opaque(slot) then
  spr_batch(slot, positions)
end

spr_debug(PLAYER, player.x, player.y)

if spr_hit(PLAYER, px, py, ENEMY, ex, ey) then
  take_damage()
end

local bg = canvas_new(640, 480)

canvas_set(bg)
rectfill(0, 0, 639, 479, 2)
canvas_set()   -- back to screen

canvas_draw(bg, 0, 0)           -- fast full-screen blit
canvas_draw(portrait, 10, 10, 3)  -- 3x scaled portrait

local bg = image_load(CART_DIR .. "background.img")

function _init()
  tm = mload(0)
  map_use(tm)
end

tilemap_draw(tm, 0, 0)

-- two-layer parallax scroll
camera(flr(bg_x), 0)
tilemap_parallax(bg_tm, 0, 0)
camera(flr(fg_x), 0)
tilemap_draw(fg_tm, 0, 0)
camera()

tilemap_set(tm, 3, 2, 5)   -- place tile 5 at column 3, row 2

local t = tilemap_get(tm, 3, 2)

map_use(tm)

local tile = mget(flr(px/16), flr(py/16))

mset(5, 3, 0)   -- clear tile at (5,3)

-- minimal from-scratch iso map: a 4x4 flat plaza, all ground level
local TW, TH, HU = 32, 16, 8
local cols, rows = 4, 4
local data, heights, ramps = {}, {}, {}
for i = 1, cols * rows do
    data[i], heights[i], ramps[i] = 1, 0, 0
end
tm = tilemap_new_iso(TW, TH, HU, cols, rows, { ground }, data, heights, ramps)

function _init()
    tm = iso_mload(0)
end

local anim = iso.new_anim(col, row)     -- settled at (col,row); pass a 3rd arg for height too
iso.start_hop(anim, new_col, new_row)   -- begin an eased glide toward a new cell
local col, row = iso.tile_pos(anim)     -- current interpolated position, every frame
iso.snap_anim(anim, col, row)           -- instant relocate, no glide (e.g. respawn)

local ox, oy = iso.center_bounds(cols, rows, tile_w, tile_h, height_unit,
    function(c, r) return data[r * cols + c + 1] end,
    320, 240)   -- screen point to center on

local iso = dofile(CART_DIR .. "isometric.lua")
local TW, TH, HU = 32, 16, 8
local tm, map, player_spr
local px, py = 2, 2
local anim

function _init()
    -- ...build tm via tilemap_new_iso() or iso_mload(0)...
    local ox, oy = iso.center_bounds(cols, rows, TW, TH, HU, function() return 0 end, 320, 240)
    map = iso.new(tm, ox, oy)
    anim = iso.new_anim(px, py)
    player_spr = spr_new(TW, TH, pix)   -- your own actor sprite
end

function _update()
    anim.t = math.min(1, anim.t + 1 / 8)
    local nx, ny = px, py
    if btnp("right") then nx = px + 1 end
    -- ...other directions, bounds/collision checks...
    if nx ~= px or ny ~= py then
        iso.start_hop(anim, nx, ny)
        px, py = nx, ny
    end
end

function _draw()
    cls(0)
    map:draw()
    local col, row = iso.tile_pos(anim)
    map:draw_actor(player_spr, col + 1, row + 1, 0, false, false)
end

sfx(note("C4"), 0.2, 0, 80)                          -- short blip
sfx(110, 1.5, 0, 90, 0, {a=10, d=200, s=60, r=300}) -- ADSR pad
sfx(220, 1.5, 0, 90, 0, {flt=1, fc=600, fq=3.0})    -- low-pass

sfx(note("A4"), 0.3, 0, 80)   -- 440 Hz
sfx(note("C#4"), 0.3, 1, 80)
sfx(note("Gb5"), 0.3, 2, 80)

local melody = {
  {note("C4"), 0.2, 0, 70},
  {note("E4"), 0.2, 0, 70},
  {note("G4"), 0.4, 0, 80},
  {0, 0.1},              -- rest
}
music(melody, true)      -- loop forever

music_stop()    -- stop all music
music_stop(2)   -- stop channel 2 only

audio_stop()   -- silence everything

snd_load(0, "music.pcm")

function _init()
  snd_load(0, "music.pcm")
  snd_play(0, true, 0, 80)   -- loop on channel 0
end

-- several simultaneous one-shots, e.g. explosions landing close together:
-- let the engine pick a free voice instead of managing a channel pool by hand
snd_play(1, false, -1, 90)

-- one kick sample, several notes of a bassline
snd_play_pitched(2, 0, note("C-3"), 55.0, 80)
snd_play_pitched(2, 0, note("E-3"), 55.0, 80)

snd_stop(0)   -- stop channel 0 only
snd_stop()    -- stop all channels

local slide = tween_new(0.4, 660, 480, "outBack")

local x, done = tween_step(slide)
canvas_draw(panel, flr(x), 100)
if done then tween_free(slide) end

tween_reset(slide)

tween_free(slide)

bx, by = bezier(t, 100,240, 200,50, 300,240)

local PATH
function _init()
  PATH = bez_render(32, 20,240, 160,40, 300,240)
end

function _update()
  local i = flr(enemy.t * 31) * 2
  enemy.x = PATH[i + 1]
  enemy.y = PATH[i + 2]
end

local ball = body_new(320, 100, 8, 1.0)

body_force(ball, 0, 0.5)   -- gravity

body_force(ball, 0, 0.5)
body_update(ball, 0.99)

local bx, by = body_pos(ball)
circfill(bx, by, 8, 9)

local vx, vy = body_vel(ball)

body_circle_collide(ball, 320, 400, 60, 0.7)

body_aabb_collide(ball, 0, 0, 639, 479, 0.6)   -- screen boundary

body_free(ball)

local s = spring_new(head, tail, 30, 0.4)

spring_update(s, 6)

spring_draw(s, 11)

spring_free(s)

expl_em = emit_new({
    cols = {104, 96, 88, 87, 3},
    size = 2, grav = 0.10,
    vx = {-5, 5}, vy = {-6, -0.5},
    life = {28, 48},
})

emit_burst(expl_em, enemy.x, enemy.y, 24)

ps = part_new(200, 0)   -- 200 particles, no trail

part_bounds(ps, 0, 0, 639, 479, 0.6)

-- force field: particles orbit the mouse
function _update()
    local mx, my = mouse()
    part_repel(ps, mx, my, 80, 4000)
    part_spring(ps, 0.03)
    part_update(ps, 0.90)
end

function _draw()
    cls(0)
    part_draw(ps, 7)
end

local tr = tween_new(0.6, 0, 1, "inOutQuad")

function _draw()
    draw_scene()
    local v, done = tween_step(tr)
    fade(v)                  -- fade out over 0.6s
    if done then next_scene() end
end

cloth_init(16, 12, 40)   -- 16x12 grid, 40px rest spacing

cloth_update(0.4, 0.99, sin(time() * 0.3) * 0.5, 3)

cloth_draw({72, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 64})

repulsor_init(400, 20)

repulsor_update(mx, 240, 80, 900, 12100, 0.0008, 0.0004, 0.97)

repulsor_draw({248, 154, 166, 191, 15}, {15, 162, 176, 192, 1}, time())

-- which enemies are hit by any bullet
local hits = {}
local result, n = ent_hit_all(bul_x, bul_y, #bul_x,
                               ene_x, ene_y, #ene_x,
                               20*20, hits)

function _init()
    if not init3d(72) then return end
    mesh_floor = load_mesh("floor.obj")
    tex_floor  = load_tex("floor.png")
end

cam(px, 0.55, pz, yaw)

function _draw()
    cam(px, 0.55, pz, yaw)
    begin_3d()
        push()
            tint(255, 255, 255)
            mesh_draw(mesh_floor, tex_floor)
        pop()
    end_3d()
end

tint(255, 80, 20)
billboard(px, py, pz, 0.3, 0.3, white_tex)

set_ambient(0.25)
set_light(0.4, -1.0, 0.3)   -- sun from upper-left, overhead (negative Y)

tex_ship = spr_to_tex(8, 2)   -- 2x2-tile (32x32) sprite grid at slot 8

room_mesh = poly_build({
    { color = 6, extrude_height = 0.2,
      vertices = {{-4,-4},{4,-4},{4,4},{-4,4}} },   -- floor
    { color = 7, pos = {0,0.2,-4}, extrude_height = 3,
      vertices = {{-4,0},{4,0},{4,0.3},{-4,0.3}} },  -- wall
})
mesh_draw(room_mesh, -1)  -- -1: untextured, uses each shape's colour

collider_mesh_add(mesh_floor, 0, 0, 0)

function _update(dt)
    local dx = (btn("right") and 1 or 0) - (btn("left") and 1 or 0)
    vy = vy - 9.8 * dt
    local nx, ny, nz, grounded = move_and_slide(px, py, pz, dx * 3 * dt, vy * dt, 0, 0.4)
    px, py, pz = nx, ny, nz
    if grounded then vy = 0 end
end

-- ground check, straight down
local hit, hx, hy, hz, nx, ny, nz, dist = raycast3d(px, py, pz, 0, -1, 0, 5)

function _init()
  local src = image_load(CART_DIR .. "bg.img")
  bg = canvas_new(640, 480)
  canvas_set(bg); canvas_draw(src, 0, 0); canvas_set()
end

{ "notes": [
    ["C4", 0.2, 0, 80],
    ["E4", 0.2, 0, 80],
    ["G4", 0.4, 0, 80],
    ["",   0.1, 0,  0]
] }

local TileWorld = require("tileworld")
local world = TileWorld.new{ tile_size = 16, cols = 128, rows = 100, solid = my_solid_grid }

world:set_grid(new_solid_grid)

world:set_cell(cx, cy, false)   -- player broke through this tile

world:set_destructible(bedrock_grid)   -- some tiles now blast-proof
world:set_destructible()               -- back to "everything diggable"

world:add_ramp("spark", { 8, 9, 10, 11 })
world:add_ramp("smoke", { 0, 1, 2, 3, 4 })

world:spawn{ x = vx, y = vy, angle = 0.25, speed = 60,
    life = 40, gravity = -0.03, size = 6, ramp = "smoke" }

function _update(dt)
    world:update()
end
function _draw()
    world:draw()
end

local dig = world:dig_ray{ x = ship.x, y = ship.y, angle = ship.angle, range = 300 }
if dig.blocked then spark_vfx(dig.end_x, dig.end_y) end
if dig.hit then melt_vfx(dig.x, dig.y) end

for _, tx, ty in TileWorld.each_cell(dig.cells) do
    on_tile_cleared(tx, ty)   -- your own bookkeeping: pickups, sprite IDs, sound
end

local Movement = require("movement")
local function is_solid(px, py) return mget(flr(px/8), flr(py/8)) > 0 end

-- every frame, after adding gravity to vy yourself:
x, y, hit_x, hit_y = Movement.move_and_slide(x, y, vx, vy, dt, is_solid)
if hit_y then vy = 0 end   -- landed on the ground / hit a ceiling
if hit_x then vx = 0 end

local hi = dget(0)   -- load high score

if score > hi_score then
  hi_score = score
  dset(0, hi_score)
end