Primeiros Passos

Pré-requisitos

Ferramenta	Versão	Notas
CMake	≥ 3.28	Exigido pelo CMakeLists.txt raiz
Ninja	qualquer	Usado pelos presets
GCC / G++	≥ 12 (C++20)	Testado com MinGW-w64 no Windows
Git	qualquer	FetchContent clona dependências no configure
GLEW	sistema	Deve estar instalado; não é baixado automaticamente
Lua 5.x	sistema	Headers + biblioteca; não é baixado automaticamente

GLEW e Lua devem ser encontráveis pelos caminhos padrão do CMake. No MSYS2/MinGW:

pacman -S mingw-w64-x86_64-glew mingw-w64-x86_64-lua

As seguintes dependências são baixadas automaticamente via FetchContent no configure (requer internet no primeiro build):

• SDL2 v2.32.8
• GLM 1.0.1
• spdlog v1.15.3
• nlohmann_json v3.12.0
• Catch2 v3.8.1 (se GUEBLY_BUILD_TESTS=ON)
• Dear ImGui (se compilando o editor)

---

Build a partir do código-fonte

1. Clone e entre no diretório

git clone https://github.com/GueblyGames/guebly-engine guebly-engine
cd guebly-engine

2. Configure com um preset

# Build de debug (para desenvolvimento)
cmake --preset debug

# Build de release (otimizado)
cmake --preset release

Diretórios de saída dos presets:

• Debug: build/debug/
• Release: build/release/

Ambos usam o gerador Ninja e definem CMAKE_CXX_STANDARD=20.

3. Compile

# Compilar tudo
cmake --build --preset debug

# Ou compilar alvos específicos
cmake --build --preset debug --target guebly_editor
cmake --build --preset debug --target guebly_runtime
cmake --build --preset debug --target guebly_tests

4. Execute

# Rodar o editor
./build/debug/editor/guebly_editor.exe

# Rodar o runtime com um script Lua
./build/debug/runtime/guebly_runtime.exe templates/boteco-tycoon/scripts/main.lua

# Rodar testes
./build/debug/tests/guebly_tests.exe

Opções do CMake

Opção	Padrão	Efeito
GUEBLY_BUILD_EDITOR	ON	Compila guebly_editor
GUEBLY_BUILD_TESTS	ON	Compila guebly_tests (baixa Catch2)
GUEBLY_BUILD_SCRIPTING	ON	Compila guebly_scripting e guebly_runtime

# Build mínimo (core + scripting, sem editor, sem testes)
cmake --preset debug -DGUEBLY_BUILD_EDITOR=OFF -DGUEBLY_BUILD_TESTS=OFF

---

Criando um novo projeto Lua

Estrutura do projeto

meu_jogo/
├── project.json       # Obrigatório: metadados do projeto
├── scenes/
│   └── main.json      # Arquivo de cena (JSON, opcional)
├── scripts/
│   └── main.lua       # Ponto de entrada
├── assets/
│   ├── player.png
│   └── bgm.ogg
└── data/
    └── config.json

project.json

{
  "name": "Meu Jogo",
  "version": "0.1.0",
  "company": "Meu Estúdio",
  "start_scene": "scenes/main.json",
  "window": {
    "title": "Meu Jogo",
    "width": 1280,
    "height": 720,
    "fullscreen": false,
    "resizable": true
  },
  "settings": {
    "target_fps": 60,
    "physics_enabled": false,
    "audio_enabled": true
  }
}

Script Lua mínimo (scripts/main.lua)

-- Estado
local player = { x = 400, y = 300, speed = 200 }
local score = 0

function on_start(entity)
    Debug.log("Jogo iniciado!")
    Audio.play_music("assets/bgm.ogg", true, 1.0)
end

function on_update(entity, dt)
    if Input.is_held("d") then player.x = player.x + player.speed * dt end
    if Input.is_held("a") then player.x = player.x - player.speed * dt end
    if Input.is_held("s") then player.y = player.y + player.speed * dt end
    if Input.is_held("w") then player.y = player.y - player.speed * dt end

    -- Limitar à tela
    player.x = math.clamp(player.x, 0, Renderer.width()  - 32)
    player.y = math.clamp(player.y, 0, Renderer.height() - 32)
end

function on_render(entity)
    Renderer.clear(0.05, 0.05, 0.1, 1)
    Renderer.draw_rect(player.x, player.y, 32, 32, 0.2, 0.8, 1, 1)
    Renderer.draw_text("Score: " .. tostring(score), 10, 10, 18)
end

function on_destroy(entity)
    Debug.log("Saindo do jogo.")
end

Rodando o jogo

guebly_runtime.exe scripts/main.lua

---

Armadilhas Comuns

1. GLEW ou Lua não encontrados no configure

O CMake vai errar com Could not find GLEW ou similar. Instale via gerenciador de pacotes:

# MSYS2
pacman -S mingw-w64-x86_64-glew mingw-w64-x86_64-lua

Certifique-se que o diretório bin do MSYS2 está no seu PATH ao rodar o CMake.

2. FetchContent trava ou falha

FetchContent requer acesso à internet. Se estiver atrás de proxy ou com internet lenta, defina:

set FETCHCONTENT_QUIET=OFF   # para ver o progresso

3. Nomes de teclas no Input

Use os nomes de teclas SDL em minúsculas: "w", "space", "return", "left ctrl", "escape". Teclas com espaço devem incluir o espaço: use "left" (não "left arrow").

4. Caminhos de assets em Lua

O runtime define o diretório de trabalho como o diretório pai do script. Use caminhos relativos a esse diretório (ex: "assets/player.png", não "../assets/player.png").

5. Entity.create vs World.create

Entity.create retorna dois inteiros (index, generation). World.create retorna um único inteiro empacotado. Use World.* para todo código novo.

---

Templates de Exemplo

Incluídos em templates/:

Template	Descrição
boteco-tycoon/	Jogo tycoon completo (Lua, cenas, localização, save system)
engine-demo/	Shooter 2D completo com inimigos, colisão, placar, save/load
empty_project/	Scaffold mínimo de projeto

# Rodar o boteco
guebly_runtime.exe templates/boteco-tycoon/scripts/main.lua

# Rodar o demo do engine
guebly_runtime.exe templates/engine-demo/main.lua