Game Loop & Window

Game Loop Callbacks

Like2D calls these global functions automatically. Implement them in your main.luau to respond to engine events.

onInit()

Called once when the application starts, before the first frame. Use this to set up the window, load assets, and initialize game state.

function onInit()
    setWindowTitle("My Game")
    setWindowSize(800, 600)
    loadImage("assets/player.png")
    loadSound("bgm", "assets/music.mp3")
    playSound("bgm", true)  -- loop background music
end

onUpdate(dt)

Called every frame before onDraw(). Use this for game logic, physics, input handling, and AI. The dt parameter is delta time in seconds since the last frame (e.g. 0.016 at 60 FPS).

Parameters:

• dt (number): Time in seconds since last frame

function onUpdate(dt)
    -- Move player using delta time for smooth frame-independent speed
    if isKeyDown("Right") then
        player.x = player.x + player.speed * dt
    end
    if isKeyDown("Space") and isGrounded then
        player.vy = -400  -- jump impulse
    end
end

onDraw()

Called every frame after onUpdate(). Use this for all rendering: clear screen, draw images, primitives, and text. Do NOT put game logic here.

function onDraw()
    clearScreen(30, 30, 50)
    renderImage("assets/player.png", player.x, player.y, 64, 64)
    drawTextDirect("Score: " .. score, 10, 10, 24, 255, 255, 255, 255)
end

onCleanup()

Called once when the application is closing. Use this for final cleanup, logging, or saving.

function onCleanup()
    print("Game shutting down...")
end

Input & Resize Callbacks

Like2D also fires these optional callbacks when input events occur or the window is resized. Implement them in main.luau to react to individual key presses, mouse events, and window changes.

onKeyPressed(key)

Called once when a key is pressed down.

Parameters:

• key (string): Name of the pressed key (e.g., "Space", "a", "Escape")

function onKeyPressed(key)
    if key == "Space" then
        player.jump()
    elseif key == "Escape" then
        print("Escape pressed - returning to menu")
    end
end

onKeyReleased(key)

Called once when a key is released.

• key (string): Name of the released key

function onKeyReleased(key)
    if key == "LShift" then
        player.running = false
    end
end

onMousePressed(button, x, y)

Called once when a mouse button is pressed.

• button (integer): 0 = left, 1 = right, 2 = middle
• x (integer): Mouse X position in screen coordinates
• y (integer): Mouse Y position in screen coordinates

function onMousePressed(btn, mx, my)
    if btn == 0 then
        print("Left click at " .. mx .. ", " .. my)
    end
end

onMouseReleased(button, x, y)

Called once when a mouse button is released.

onMouseScroll(x, y)

Called when the mouse wheel is scrolled. The x and y values represent the scroll delta (positive = right/up, negative = left/down).

function onMouseScroll(sx, sy)
    if sy > 0 then
        setCameraZoom(getCameraZoom() * 1.1)
    elseif sy < 0 then
        setCameraZoom(getCameraZoom() / 1.1)
    end
end

onResize(width, height)

Called when the window is resized. Use this to adjust UI layout or letterboxing settings dynamically.

• width (integer): New window width in pixels
• height (integer): New window height in pixels

function onResize(w, h)
    print("Window resized to " .. w .. "x" .. h)
end

Window Management Functions

setWindowTitle(title)

Sets the window title text.

Parameters:

• title (string): The new window title

setWindowTitle("My Awesome Game")

setWindowSize(width, height)

Sets the window dimensions in pixels.

Parameters:

• width (integer): Window width in pixels
• height (integer): Window height in pixels

setWindowSize(1024, 768)

getWindowSize()

Gets the current window dimensions.

Returns:

• width (integer): Current window width
• height (integer): Current window height

local w, h = getWindowSize()
print("Window size: " .. w .. "x" .. h)

setFullscreen(fullscreen)

Toggles fullscreen mode.

Parameters:

• fullscreen (boolean): true for fullscreen, false for windowed

setFullscreen(true)   -- Enable fullscreen
setFullscreen(false)  -- Disable fullscreen

setEscapeQuits(boolean)

Sets whether ESC key automatically quits the game. Default: true.

setEscapeQuits(false)

Window Functions (Letterboxing)

Functions to manage aspect ratio scaling. Letterboxing ensures your game retains its original proportions (anti-stretch) with automatic black/colored bars on different monitor aspect ratios.

setLogicalSize(width, height)

Sets the fixed base internal resolution for your game mechanics and rendering coordinates.

Parameters:

• width (integer): Target logical width (e.g., 800).
• height (integer): Target logical height (e.g., 600).

getLogicalSize()

Retrieves the currently configured logical resolution.

Returns:

• width (integer), height (integer)

setUseLetterbox(use)

Toggles the global letterbox scaling system state.

Parameters:

• use (boolean): Set true to lock aspect ratio, or false to stretch visuals completely.

setLetterboxColor(red, green, blue)

Changes the background color of the letterbox sidebars (Default color may vary due to memory buffer).

Parameters:

• red, green, blue (integer): RGB values ranging from 0 to 255.

Implementation Guide (onInit):

function onInit()
    setWindowSize(1280, 720)       -- Physical Window Size
    setLogicalSize(800, 600)       -- Game Canvas Size
    setUseLetterbox(true)          -- Lock aspect ratio
    setLetterboxColor(0, 0, 0)     -- Force clean cinematic black bars
end