API Lua — Referência Completa

Fonte: scripting/src/lua_engine.cpp e scripting/src/bindings/.

A VM Lua é criada por LuaEngine::init(). Todas as bibliotecas padrão Lua são carregadas (luaL_openlibs). Um sandbox é aplicado: os globais os e debug são removidos; io também é removido. Use as APIs do engine abaixo em vez de acesso direto a arquivos/OS.

Debug

Global: Debug

Função	Parâmetros	Retorno	Descrição
`Debug.log(msg)`	`msg: string`	—	Loga em nível INFO via spdlog. Prefixado `[Lua]`.
`Debug.warn(msg)`	`msg: string`	—	Loga em nível WARN.
`Debug.error(msg)`	`msg: string`	—	Loga em nível ERROR.

Debug.log("Jogo iniciado")
Debug.warn("Vida baixa: " .. tostring(hp))
Debug.error("Textura não encontrada!")

Time

Global: Time

Função	Parâmetros	Retorno	Descrição
`Time.delta()`	—	`number`	Delta time do frame atual em segundos.
`Time.elapsed()`	—	`number`	Tempo total desde o início do engine, em segundos.
`Time.fps()`	—	`number`	Quadros por segundo (média rolante).
`Time.scale()`	—	`number`	Escala de tempo atual (1.0 = normal).
`Time.set_scale(s)`	`s: number`	—	Define escala de tempo. 0 = pausado, 0.5 = metade, 2 = dobro.
`Time.frame()`	—	`integer`	Contador de frames desde o início.

Input

Global: Input

Nomes de teclas são nomes SDL em minúsculas (ex: "w", "space", "left ctrl", "return").

Teclado

Função	Parâmetros	Retorno	Descrição
`Input.is_pressed(key)`	`key: string`	`boolean`	Verdadeiro apenas no primeiro frame que a tecla é pressionada.
`Input.is_held(key)`	`key: string`	`boolean`	Verdadeiro todo frame que a tecla está pressionada.
`Input.is_released(key)`	`key: string`	`boolean`	Verdadeiro apenas no frame em que a tecla é solta.

Mouse

Função	Parâmetros	Retorno	Descrição
`Input.mouse_position()`	—	`x, y: number`	Posição atual do mouse em pixels da janela.
`Input.mouse_delta()`	—	`x, y: number`	Movimento do mouse neste frame.
`Input.mouse_button(btn)`	`btn: integer`	`boolean`	Estado do botão: 1=esquerdo, 2=meio, 3=direito.
`Input.set_mouse_captured(captured)`	`captured: boolean`	—	Ativa SDL relative mouse mode.
`Input.scroll()`	—	`number`	Delta da roda de scroll neste frame.

Gamepad

Função	Parâmetros	Retorno	Descrição
`Input.gamepad_axis(player, axis)`	`player, axis: integer`	`number`	Valor do eixo [-1, 1].
`Input.gamepad_button(player, btn)`	`player, btn: integer`	`boolean`	Estado do botão do gamepad.

Renderer (2D)

Global: Renderer

Wraps Renderer2D (OpenGL 3.3, quads em batch). Câmera ortográfica com origem no canto superior esquerdo.

Função	Parâmetros	Retorno	Descrição
`Renderer.clear(r?, g?, b?, a?)`	RGBA floats	—	Limpa buffer de cor e profundidade.
`Renderer.begin_frame()`	—	—	Inicia um novo batch.
`Renderer.end_frame()`	—	—	Envia batch e troca buffers.
`Renderer.draw_rect(x, y, w, h, r?, g?, b?, a?)`	pos, size, cor	—	Quad preenchido. `(x,y)` é o canto superior esquerdo.
`Renderer.draw_quad(cx, cy, w, h, r?, g?, b?, a?)`	centro, size, cor	—	Quad preenchido. `(cx,cy)` é o centro.
`Renderer.draw_texture(path, x, y, w?, h?)`	path, pos, size?	—	Carrega e desenha textura.
`Renderer.load_texture(path)`	`path: string`	`TextureID: integer`	Pré-carrega textura, retorna ID GL.
`Renderer.draw_sprite(texId, x, y, w?, h?, rot?, alpha?)`	texId, pos, size, rot, alpha	—	Desenha sprite com rotação e alpha.
`Renderer.draw_line(x1, y1, x2, y2, r?, g?, b?, a?, thickness?)`	dois pontos, cor, espessura	—	Linha espessa via quad rotacionado.
`Renderer.draw_circle(cx, cy, radius, r?, g?, b?, a?)`	centro, raio, cor	—	Contorno de círculo com 32 segmentos.
`Renderer.draw_text(text, x?, y?, size?, r?, g?, b?, a?)`	text, pos, size, cor	—	Renderiza texto via stb_truetype.
`Renderer.set_camera(x?, y?, zoom?, rot?)`	pos/zoom/rot	—	Define câmera ortográfica 2D.
`Renderer.width()`	—	`integer`	Largura da viewport em pixels.
`Renderer.height()`	—	`integer`	Altura da viewport em pixels.

function on_render(entity)
    Renderer.clear(0.1, 0.1, 0.15, 1)
    Renderer.draw_rect(50, 50, 200, 100, 1, 0.2, 0.2, 1)
    Renderer.draw_texture("assets/player.png", px, py, 64, 64)
    Renderer.draw_text("Score: " .. score, 10, 10, 18, 1, 1, 0, 1)
end

UI

Global: UI

Elementos de UI immediate-mode via Renderer2D. Coordenadas em pixels de tela.

Função	Parâmetros	Retorno	Descrição
`UI.panel(x, y, w, h, r?, g?, b?, a?)`	pos, size, cor	—	Painel de fundo.
`UI.label(text, x, y, size?, r?, g?, b?, a?)`	text, pos, size, cor	—	Rótulo de texto.
`UI.progress_bar(x, y, w, h, value, r?, g?, b?, a?)`	pos, size, valor [0,1], cor	—	Barra de progresso.
`UI.button(text, x, y, w, h)`	text, pos, size	`boolean`	Botão clicável. Retorna `true` no frame do clique.

function on_render(entity)
    UI.panel(0, 0, 200, 50, 0, 0, 0, 0.6)
    UI.label("Score: " .. score, 10, 12, 20, 1, 1, 0, 1)
    UI.progress_bar(10, 40, 180, 8, hp / max_hp, 0.2, 0.8, 0.2, 1)
    if UI.button("Play", 300, 200, 120, 40) then
        state = "playing"
    end
end

Audio

Global: Audio

SoundID é um handle inteiro retornado pelas funções play. 0 é o ID inválido.

Função	Parâmetros	Retorno	Descrição
`Audio.play(path, vol?)`	`path, vol?` (padrão 1.0)	`SoundID`	Toca um som one-shot.
`Audio.play_music(path, loop?, fade?)`	`path, loop?, fade?` (padrão 0.5s)	`SoundID`	Toca trilha; para a música anterior com fade.
`Audio.stop_music()`	—	—	Para música atual imediatamente.
`Audio.stop(id)`	`id: SoundID`	—	Para e libera instância de som.
`Audio.pause(id)`	`id: SoundID`	—	Pausa sem liberar.
`Audio.resume(id)`	`id: SoundID`	—	Retoma som pausado.
`Audio.set_volume(id, vol)`	`id, vol: number`	—	Volume por instância [0, 1].
`Audio.set_master_volume(vol)`	`vol: number`	—	Volume master.
`Audio.fade_in(id, duration)`	`id, duration`	—	Fade de 0 ao volume base.
`Audio.fade_out(id, duration, stop?)`	`id, duration, stop?`	—	Fade para 0, opcionalmente para.

Physics

Global: Physics

Aviso: A implementação de física de corpos rígidos (Jolt) é um stub. Use Physics.overlap para AABB 2D.

Função	Parâmetros	Retorno	Descrição
`Physics.overlap(x1,y1,w1,h1, x2,y2,w2,h2)`	dois AABB	`boolean`	Colisão AABB pura.
`Physics.check_collision(a, b)`	dois tables `{x,y,w,h}`	`boolean`	Alias para overlap via tables.
`Physics.raycast(ox,oy,oz, dx,dy,dz, maxDist?)`	origem, direção, dist max	`hit, dist, entity`	Raycast 3D (stub — retorna `hit=false`).
`Physics.set_gravity(x, y, z)`	—	—	Define vetor gravidade.

World (ECS)

Global: World

Entidades são representadas como um único inteiro empacotado: (index << 16) | generation.

Função	Parâmetros	Retorno	Descrição
`World.create(name?)`	`name?`	`entity: integer`	Cria entidade com Transform.
`World.destroy(entity)`	`entity`	—	Destrói entidade e filhos recursivamente.
`World.is_alive(entity)`	`entity`	`boolean`	Verificação de geração.
`World.find_by_name(name)`	`name: string`	`entity` ou `nil`	Busca linear por nome.
`World.get_transform(entity)`	`entity`	`table`	`{position, rotation, scale}` — rotação em graus.
`World.set_transform(entity, t)`	`entity, table`	—	Define Transform a partir da table.
`World.add_tag(entity, tag)`	`entity, tag: string`	—	Adiciona tag de string à entidade.
`World.has_tag(entity, tag)`	`entity, tag: string`	`boolean`	—
`World.set_parent(child, parent)`	`child, parent`	—	Vincula filho ao pai.
`World.get_children(entity)`	`entity`	`table[]`	Array de filhos.

SaveSystem

Global: SaveSystem

Serializa tables Lua como JSON usando nlohmann/json.

Função	Parâmetros	Retorno	Descrição
`SaveSystem.save(filename, table)`	`filename: string, table`	`boolean`	Salva table como JSON. Retorna `true` se OK.
`SaveSystem.load(filename)`	`filename: string`	`table` ou `nil`	Carrega JSON e retorna como table Lua.

-- Salvar
SaveSystem.save("save.json", { score = 1000, level = 3 })

-- Carregar
local data = SaveSystem.load("save.json")
if data then
    score = data.score
end

Vec3

Global: Vec3

Um Vec3 em Lua é uma table {x, y, z}.

Função	Parâmetros	Retorno	Descrição
`Vec3.new(x?, y?, z?)`	numbers	`vec3 table`	Cria Vec3.
`Vec3.add(a, b)`	vec3, vec3	vec3	Soma componente a componente.
`Vec3.sub(a, b)`	vec3, vec3	vec3	Subtração.
`Vec3.mul(a, s)`	vec3, number	vec3	Multiplicação escalar.
`Vec3.dot(a, b)`	vec3, vec3	number	Produto escalar.
`Vec3.cross(a, b)`	vec3, vec3	vec3	Produto vetorial.
`Vec3.length(a)`	vec3	number	Comprimento euclidiano.
`Vec3.normalize(a)`	vec3	vec3	Vetor normalizado.
`Vec3.lerp(a, b, t)`	vec3, vec3, number	vec3	Interpolação linear.
`Vec3.distance(a, b)`	vec3, vec3	number	Distância euclidiana.

Math Extensions

O math padrão do Lua é estendido com:

Função	Parâmetros	Retorno	Descrição
`math.clamp(v, lo, hi)`	numbers	number	Limita `v` ao intervalo `[lo, hi]`.
`math.lerp(a, b, t)`	numbers	number	Interpolação linear: `a + (b-a)*t`.
`math.deg2rad(degrees)`	number	number	Graus para radianos.
`math.rad2deg(radians)`	number	number	Radianos para graus.

Event

Global: Event

Sistema pub/sub dentro dos scripts Lua. Eventos identificados por string.

Função	Parâmetros	Retorno	Descrição
`Event.subscribe(name, callback)`	`name, function`	`handle: integer`	Registra callback. Retorna handle para cancelamento.
`Event.unsubscribe(name, handle)`	`name, handle`	—	Remove callback pelo handle.
`Event.publish(name, ...)`	`name, ...any`	—	Chama todos os callbacks do evento. Síncrono.

Callbacks do Ciclo de Vida

Quando o runtime carrega um arquivo Lua, procura estas funções globais:

Callback	Assinatura	Quando chamado
`on_start`	`function(entity_index)`	Uma vez, após carregar o script.
`on_update`	`function(entity_index, dt)`	Todo frame. `dt` em segundos.
`on_render`	`function(entity_index)`	Todo frame, após `on_update`.
`on_destroy`	`function(entity_index)`	Uma vez, ao sair do jogo.

Debug​

Time​

Input​

Teclado​

Mouse​

Gamepad​

Renderer (2D)​

UI​

Audio​

Physics​

World (ECS)​

SaveSystem​

Vec3​

Math Extensions​

Event​

Callbacks do Ciclo de Vida​