Getting Started – Lua SDK

Alpha – GoudEngine is under active development. APIs change frequently. Report issues

This guide covers installing the Lua SDK, running scripts through the embedded runner, and using the core engine APIs from Lua.

See also: C# guide – Python guide – TypeScript guide – Rust guide – Swift guide – Go guide – Kotlin guide

Prerequisites

• Lua 5.4 or later
• LuaRocks 3.x (for standalone module installation)
• Rust toolchain – needed to build the native engine library

How It Works

The Lua SDK uses mlua to embed Lua 5.4 inside the Rust engine. There are two ways to use it:

1. Embedded runner (recommended for games) – The lua-runner binary loads your Lua scripts and registers all engine bindings as globals automatically.
2. Standalone module (via LuaRocks) – A require-able module for standalone Lua interpreters that provides key constants and version info.

Building the Native Library

git clone https://github.com/aram-devdocs/GoudEngine.git
cd GoudEngine
cargo build --release

Installation

Embedded Runner (recommended)

The embedded runner is built as part of the engine. No separate installation is needed:

cargo build --release
# The runner is at examples/lua/runner/

LuaRocks Module

For standalone Lua scripts that need key constants:

cd sdks/lua
luarocks make goudengine-scm-1.rockspec

Or build manually:

cd sdks/lua/luarocks
make          # builds the native library via cargo
make install  # installs Lua modules and the native library

First Project

Create main.lua:

-- When running through the embedded runner, engine globals are
-- registered automatically. No require() needed.

local SCREEN_W = 800
local SCREEN_H = 600

-- The game loop is driven by the embedded runtime.
-- on_update is called every frame with delta time.

function on_init()
    -- Called once when the script loads.
    -- Load textures, set up initial state here.
end

function on_update(dt)
    -- Called every frame.
    -- dt is the elapsed seconds since the last frame.

    if is_key_just_pressed(Key.escape) then
        request_close()
    end
end

function on_draw()
    -- Called every frame after on_update.
    -- Draw sprites and shapes here.
end

Run it through the embedded runner:

./dev.sh --sdk lua --game flappy_bird

Drawing a Sprite

Load textures in on_init, then draw each frame in on_draw.

local player_tex

function on_init()
    player_tex = load_texture("assets/player.png")
end

function on_draw()
    draw_sprite(player_tex, 400, 300, 64, 64, 0)
end

draw_sprite takes the texture handle, center x, center y, width, height, and rotation in radians.

Handling Input

Keyboard

function on_update(dt)
    -- One-shot: true only on the frame the key goes down
    if is_key_just_pressed(Key.space) then
        -- jump
    end

    -- Held: true every frame the key is down
    if is_key_pressed(Key.w) then
        y = y - speed * dt
    end
    if is_key_pressed(Key.s) then
        y = y + speed * dt
    end
    if is_key_pressed(Key.a) then
        x = x - speed * dt
    end
    if is_key_pressed(Key.d) then
        x = x + speed * dt
    end
end

Mouse

function on_update(dt)
    if is_mouse_button_pressed(MouseButton.left) then
        local mx = mouse_x()
        local my = mouse_y()
        -- click action at (mx, my)
    end
end

Using the LuaRocks Module

For standalone scripts that only need constants (not the full engine runtime):

local goud = require("goudengine")
print(goud.VERSION)  -- "0.0.832"

-- Access key constants
local Key = goud.constants.key
print(Key.space)  -- 32

Running the Example Game

The repository includes a complete Flappy Bird clone in Lua:

git clone https://github.com/aram-devdocs/GoudEngine.git
cd GoudEngine
cargo build --release
./dev.sh --sdk lua --game flappy_bird

Source is in examples/lua/flappy_bird/.

Platform Support

Code Generation

The Lua SDK constants module is auto-generated by codegen/gen_lua.py. Do not hand-edit the generated files. Regenerate with:

python3 codegen/gen_lua.py

Next Steps

• Lua SDK README – Lua SDK documentation
• Lua examples source – complete game source code
• Build Your First Game – end-to-end minimal game walkthrough
• Example Showcase – current cross-language parity matrix
• SDK-first architecture – how the engine layers fit together
• Development guide – building from source, version management, git hooks
• Other getting started guides: C# – Python – TypeScript – Rust – Swift – Go – Kotlin