Tutorial Processing.GBA

Este é um tutorial sobre como utilizar a biblioteca Processing.gba – uma biblioteca em C que desenvolvemos para poética computacional que funciona em Game Boy Advance. Aqui não temos como intuito fazer um tutorial sobre lógica de programação, como hackear algum console ou como desenvolver algo complexo, sem mesmo como piratear um jogo. Longe disso, aqui temos como finalidade apresentar duas (2) coisas:

O que instalar para que as coisas funcionem corretamente; e
Primeiros passos para a criação do nosso primeiro “jogo”.

Algumas destas coisas já apresentamos página do repositório do projeto, mas creio que seja importante deixar aqui documentado.

Antes que alguém comente algo como “você não definiu tal conceito da maneira mais correta”, “eu faço isso de tal outro modo”, “mas eu prefiro tal outro programa”. Já deixo aqui minha resposta: “Estou fazendo isso de maneira simplificada, para que pessoas que não necessariamente são da área consigam entender alguma coisa. Então seria uma boa que você fizesse um tutorial também. Vai agregar mais para a comunidade como um todo. “. 🙂

Ressalto aqui que, mesmo apoiando as iniciativas de software de código livre e aberto, tomo como base que a maioria das pessoas ainda utilizam sistema Windows. Então, mesmo que a maioria das coisas indicadas aqui sirvam para distribuições Linux e MacOS, ainda darei maior foco ao sistema operacional Windows.

Tendo apresentado aqui nosso objetivo com essa postagem, creio que podemos dar início ao nosso tutorial.

1. O QUE INSTALAR?

Aqui nós vamos precisar basicamente de cinco (5) coisas:

DevKitPro, que fornece um terminal com um compilador e uma biblioteca de funções que dão suporte para criação de jogos para GBA e outras plataformas;
Algo que nos ajude a editar o código e que destaque diferentes partes como funções, variáveis e etc. Poderíamos utilizar qualquer editor de texto para esse propósito, mas indico aqui o uso de algum Ambiente Integrado de Desenvolvimento (Integrated Development Environment – IDE);
Um emulador que suporte jogos de Game Boy Advance – os jogos de GBA normalmente estão em formato .gba, então somente é necessário que seja um emulador capaz de emular tal formato;
Um conversor de imagens (formatos .jpeg, .png e entre tantos outros) para linguagem C; e
Uma cópia da biblioteca Processing.gba, algo que pode ser encontrado no github do projeto.

1.1 DEVKITPRO

Independente da nossa biblioteca, para a criação de qualquer jogo GBA é fundamental ter algum compilador e bibliotecas que auxiliem neste propósito. Pelo o que eu encontrei online, as nossas melhores opções seriam o DevKit Advance e o DevKitPro. Ficaremos aqui com o DevKitPro, pois acredito que tenha instalação e uso mais fácil, além de fornecer um terminal que serve como um compilador (de modo simplificado, seria algo que traduz o nosso código escrito em uma linguagem específica em um programa).

Para as pessoas que utilizam Windows, o download e a instalação podem ser realizados por meio deste repositório: https://github.com/devkitPro/installer/releases

Captura de tela do repositório do DevkitPro com comentário para local onde clicar para baixar o arquivo

Após finalizar o download, é só abrir o instalador e apertar próximo (next) até o final.

Já para os que utilizam Linux ou MacOS, sugiro que sigam as instruções deste link: https://github.com/devkitPro/pacman/releases/tag/v6.0.2

Após a instalação teremos o programa MSys2. Ele funciona como um terminal que vamos utilizar para compilar nosso código. Por hora, basta deixa-lo instalado e, mais adiante, quando formos criar nosso primeiro projeto usando a biblioteca, vamos utilizar o programa.

MSys2 localizado na barra iniciar do Windows

1.2 INSTALAÇÃO DE ALGUMA IDE

A edição de um código em um computador pode ser feito até mesmo por um programa de bloco de notas, porém não é algo muito indicado. As IDEs, por sua vez são os ambientes que foram desenvolvidos para o propósito de programar, então elas possuem algumas ferramentas que facilitam nossa vida. A escolha de alguma IDE vai muito da preferência do/a programador/a, assim como dos requisitos da máquina e do sistema operacional. Têm algumas IDEs que são relativamente simples e boas para uso, tal como Notepad++, que é um bloco de notas mais poderoso, ou o Sublime, que é um ambiente que permite o uso de múltiplas linguagens com marcações.

Depois de testar várias nos últimos anos, vou recomendar aqui o uso do Visual Studio Code. Não sou fã do uso de software proprietário, mas recomendo o programa fortemente para programadores/as que ainda estão começando, pois é compatível tanto com Windows, MacOS e Linux, têm um instalador fácil, é popular, em vários ambientes acadêmicos e empresas, e, por fim, têm várias ferramentas disponíveis para o desenvolvimento de outros programas além do escopo do uso da nossa biblioteca.

Para instalar o Visual Studio, é só acessar o link, baixar e seguir com a instalação: https://visualstudio.microsoft.com/pt-br/

1.3 EMULADOR DE GBA

Tal como na escolha de alguma IDE, escolher um emulador para GBA depende de pessoa para pessoa, pelas suas preferências e familiaridade. Existem múltiplos emuladores que vão fazer o trabalho de rodar o programa que vamos construir. Inclusive, para os que tiverem um adaptador de cartão sd para cartucho GBA e um console, é possível rodar o jogo direto no videogame. Pessoalmente, eu sempre utilizei o Visual Boy Advance.

Para usar o Visual Boy Advance, basta fazer o download do programa e extrair o programa em algum diretório do seu computador. Depois é necessário configurar os controles, mudar a escala de tamanho de tela e pronto. É uma boa ideia abrir um arquivo .gba qualquer e deixar o Visual Boy como programa padrão para esse tipo de arquivo.

Sitio para download do Visual Boy: https://visualboyadvance.org/

1.4 CONVERSOR DE IMAGENS

Tal como nos passos anteriores, também podemos afirmar que existem múltiplos conversores de imagens para código C. Não vamos utilizar para todos os projetos, mas é uma boa já ter um programa a mão para fazer isso. Eu uso o GBA GFX Converter, que está disponível no principal sítio de desenvolvimento de jogos GBA, o GBADEV.org.

Captura de tela da interface do GFX Converter

Link para download do GBA GFX Converter: https://gbadev.org/tools.php?showinfo=147

O 3DSage fez um tutorial de criação de roms para GBA e apresenta um ótimo modo para utilizar o programa de maneira fácil: https://youtu.be/6ecgELrwAnQ?si=F1-216dZbZ7yBPbU

1.5 A BIBLIOTECA PROCESSING.GBA

Finalmente, para instalar a biblioteca, somente precisaremos fazer mais algumas coisas super simples.

A primeira delas é ir até o repositório, na parte de Releases, baixar o arquivo .zip da última versão da biblioteca. Link para a seção de releases do repositório: https://github.com/Umbalab/processingGBA/releases.

Captura de tela do Github, do local onde ficam os últimos lançamentos da biblioteca, com indicação do arquivo que deve ser baixado.

Depois de baixar, é só abrir o arquivo .zip e arrastar a pasta para o diretório C:/ do computador.

Captura de tela do arquivo zip aberto no programa Winrar, com indicação da pasta para arrastar para o diretório C:

Pronto! Agora podemos começar a usar a biblioteca! 🙂

2. NOSSO PRIMEIRO PROJETO COM A BIBLIOTECA

Após termos realizado as devidas instalações descritas no passo anterior, vamos dar os primeiros passos para nosso primeiro projeto usando a biblioteca.

1 Primeiro, vamos começar copiando a pasta “Template” para um outro local. Ela estará localizada em “C:\ProcessingGBA\Examples\BasicFunctions”. Basta localizar o ponteiro do mouse acima da pasta, apertar com o botão direito e clicar em “copiar”. Senão, selecionar a pasta e apertar as teclas Ctrl+c. Depois ir até outro diretório, apertar com o botão direito e apertar em “colar”, ou, em outro diretório apertar as teclas Ctrl+d. Depois disso, vamos dar outro nome a esta pasta, algo como “ExemploTutorial”. Para isso, com a pasta selecionada, vamos dar outro clique e renomear. É importante que o novo nome da pasta não contenha espaços, pois pode dar problema quando formos construir nossa ROM.

Como sugestão, talvez seja interessante criar uma pasta “processingGBAProjetos” dentro do diretório de documentos.

Captura de tela com o local do diretório e indicação de qual pasta copiar.

Indicação de outro diretório para onde vamos copiar nosso template e depois da pasta colada.

Depois de termos colado e renomeado nosso template, vamos abrir o programa MSys2, que instalamos anteriormente. O caminho que vamos seguir é abrindo o menu iniciar, depois vamos em devkitPro e clicar em Msys2.

Localização do MSys2 no menu iniciar do Windows. Estou usando aqui o Windows 10, no 11 é basicamente a mesma coisa, mas em um menu centralizado.

O Msys2 é como se fosse um terminal, um programa que damos comandos em texto para que ele execute tarefas.

Nele, vamos escrever o comando “cd”, que significa “change directory” (mudar diretório).

Depois de escrever cd, damos espaço e arrastamos a pasta do nosso exemplo de tutorial para dentro do terminal. Em seguida, apertamos Enter. Vejam que a escrita ao lado do seu nome de usuário vai estar referente ao nosso diretório.

Nosso terminal Msys depois de escrevermos cd, apertar espaço e arrastar o diretório para dentro.

Depois de apertarmos a tecla Enter, o Msys estará com um encaminhamento para nosso diretório.

2. Como segundo passo, vamos entrar na pasta “source” dentro do nosso exemplo. Lá vamos localizar um arquivo chamado “scene”. Vamos abrir o scene com a nossa IDE, nesse caso, com o Visual Studio.

Localização do arquivo scene no diretório. Dar dois cliques sobre ele para abrir na IDE.

Com o arquivo aberto na nossa IDE, vamos ter algumas funções de base, sendo essas setup(){}, draw(){} e buttons(){}. “E é aqui que a magia acontece”.

Tela do Visual Studio Code com o arquivo scene aberto.

Vamos começar escrevendo “Ola Mundo”, para começarmos a programar “entrando com o pé direito”.

Para isso, dentro da função setup() e da função draw(), vamos escrever o seguinte:

void setup() {
    textFont(“fixed_8x8_font”); // função para definir a tipografia (fonte) que vamos usar, textFont(“nome da fonte pré-definida na biblioteca”)
}
void draw() {
    background(0,0,0); // função para mudar cor do pano de fundo, background(valores de vermelho de 0 até 31, valores de verde de 0 até 31, valores azul de 0 até 31)
    fill(31,31,31); // função para mudar cor de preenchimento de objetos, fill(valores de vermelho de 0 até 31, valores de verde de 0 até 31, valores azul de 0 até 31)
    text(“Ola Mundo”, 40, 20); //função para desenhar texto na tela, text(“texto entre áspas duplas”, posição em x, posição em y)
}

Isso vai ficar assim dentro do Visual Studio:

Captura de tela da escrita do código dentro do Visual Studio.

Depois de termos escrito o código, vamos salvar o arquivo, apertando Ctrl+s. Depois, vamos voltar ao Msys, escrever o comando make (que pode ser traduzido como “fazer”) e apertar a tecla Enter. Em alguns instantes, o terminal do Msys vai apresentar a mensagem: “ROM fixed!”, indicando que compilamos nosso software.

Captura de tela do mysys aberto com o comando make escrito e ao fundo o código no Visual Studio.

Tela do Mysis indicando que o software foi compilado.[/caption]

Parabéns, nosso programa está pronto! Agora vamos na pasta e abrir a room usando nosso emulador para ver em funcionamento.

Indo na pasta raiz do nosso projeto, perceba que agora existe um arquivo .gba com o nome da pasta. Vamos abrir ele com o nosso emulador.

Captura de tela da ROM em execução no emulador Visual Boy Advance

Agora que fizemos nosso primeiro código ser compilado como ROM de GBA, podemos explorar outros exemplos contidos na biblioteca, copiando para outro diretório, editando e compilando. Boa diversão! 🙂

Mateus F. Lima Pelanda,

Curitiba, 24 de julho de 2025.