DEV Community: StealthC

[EN] Gatonauta: GameDev.tv GameJam 2025 Experience

StealthC — Wed, 28 May 2025 17:48:12 +0000

Translation: Este artigo também está disponível em Português

I decided to join the GameDev.tv game jam (GameDev.tv Game Jam 2025 - Free Course For All Submissions! - itch.io), which is a great choice for anyone getting started with game development. The community is very welcoming, mostly made up of students and beginners, and there's a lot of active and constructive feedback exchange. Also, everyone who submits a game gets a free course, which is an amazing perk if you’re just starting out!

This is a 10-day jam, and the chosen theme was "Tiny World". Last year, I joined with a game called Gataria by StealthC, made for the theme "Last Stand", and it got a lot of positive feedback. I already knew I wanted to make another game with a cat protagonist, and as soon as the theme was announced, I started thinking about how to make it fit.

This time, I decided to go big. Way bigger than Gataria. I knew I was risking not finishing in time, especially since most of the 10 days were weekdays and I had to balance it with my regular job.

Choosing Tools and Initial Scope...

My idea was to make a game focused on survival, exploration, and crafting, heavily inspired by games like Factorio and Forager. I also wanted to implement a gravity mechanic on small planets, something like Super Mario Galaxy, but in 2D.

I chose to use Godot Engine (went all in with the beta version 4.5 dev3), which I know pretty well and lets me develop quickly. Its Web builds are lightweight and perfect for game jams, and the community is super active, which helps a lot when solving problems.

One thing I hadn’t done before, but decided to try this time, was setting up a CI pipeline using GitHub. That way, every time I pushed to the main branch, the game would be automatically built and uploaded to Itch.io. It helped me track progress, get testers earlier, and catch bugs faster.

Here’s the workflow I used (if you want to try it yourself, remember to adapt the keys and the Godot version to your own project):

name: Export and Upload to Itch.io

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Export Godot project
        id: export
        uses: firebelley/godot-export@v6.0.0
        with:
          godot_executable_download_url: https://github.com/godotengine/godot-builds/releases/download/4.5-dev4/Godot_v4.5-dev4_linux.x86_64.zip
          godot_export_templates_download_url: https://github.com/godotengine/godot-builds/releases/download/4.5-dev4/Godot_v4.5-dev4_export_templates.tpz
          relative_project_path: ./
          archive_output: true
          cache: true

      - name: Upload to Itch.io
        uses: Ayowel/butler-to-itch@v1
        with:
          butler_key: ${{ secrets.ITCHIO_API_KEY }}
          itch_user: YOUR_ITCHIO_USERNAME
          itch_game: YOUR_GAME_NAME
          version: ${{ github.ref_name }}
          files: ${{ steps.export.outputs.archive_directory }}/Web.zip

A Pretty Ambitious Concept...

From the start, it was clear the scope would be a challenge. I wanted the game to include:

A survival system, with hunger and resource management
Combat and action elements
Dungeons, for exploration and extra challenges
A grappling hook, to attach to asteroids or pull objects
Localization, so it could be played in English and Portuguese

With that scope, a playthrough would take a while. So a save system was a must. I started building that first, which took me almost an entire day, plus time to plan the overall structure of the game.

Here’s my initial sketch and the AI-generated version:

Reinventing Gravity From Scratch...

On day two, I tackled one of the biggest technical challenges: movement with gravity on planetoids. It sounded easy in theory: just make gravity point toward the planet’s center. In practice... not that simple.

The solution I found was to calculate all movement (walking, jumping, gravity) as if it were a regular 2D Cartesian plane. Only at the end did I rotate the final movement vector to align it with the planet’s surface. It ended up feeling pretty smooth and intuitive.

if is_on_floor():
    _local_velocity.x = input_x * current_planet.side_velocity
else:
    _local_velocity.x = lerp(_local_velocity.x, input_x * current_planet.side_velocity / 2.0, 0.1) # Smooth air control
...

var gravity_center = current_planet.global_position
var direction_to_center = (gravity_center - global_position).normalized()

...

var target_rotation = direction_to_center.angle() - PI / 2.0

...

var local_rotated = _local_velocity.rotated(target_rotation).normalized() * abs(_local_velocity.x)
velocity = local_rotated
velocity += _gravity_velocity.rotated(target_rotation)
velocity += _jetpack_velocity.rotated(global_rotation)
move_and_slide()

The game has two basic physics modes:

On planets: with gravity and lateral movement
In space: no gravity, fixed camera, and free rotation + propulsion

Of course, problems came up. In Web builds, physics started acting weird: probably due to floating point precision loss. After a lot of trial and error, I found that using square collision for the player and circle collision for planets fixed a bunch of it. Using capsules or circles for the player caused a strange bug: moving faster to one side, which got worse over time.

Racing Against Time and Using AI

For the next five days, I spent my daytime working, and only had time to work on the game late at night, usually already exhausted and not thinking straight. So I focused on building assets: sprites, planets, items, sounds, music, etc.

And that’s when I hit a hot topic: using AI to create assets.

Yeah, it’s a controversial subject in game dev, and for good reason. AI tools have become really powerful, especially for solo devs or small teams, which is basically the case in most game jams. When time is short and you don’t have all the skills needed (art, sound, music...), AI can be a huge help.

I’m not a professional artist. Creating all assets from scratch: sprites, sound effects, music, UI... just wouldn’t be realistic in a few days. So yes, I used AI tools to speed things up.

But I believe it’s important to think about how and why we use AI. It shouldn’t replace human creativity (at least not right now), but extend it. I used it to bring my ideas to life: rough sketches, textures, sounds. Almost everything needed editing, rework, adjustments to fit the game’s style.

In that sense, AI is just another tool, like a sound effect generator, for example, jsfxr - 8 bit sound maker, which I also used. It helps turn ideas into something playable, especially when you’re stuck on skills you don’t have.

Of course, I also understand the criticism. There are valid concerns around how models are trained (often using artists’ work without consent) and how it affects the creative industry.

To me, the biggest problems aren’t about the AI itself, but how the entire system around it is structured: tech monopolies, business models, etc. It’s a deeper issue.

In the context of a game jam, where we’re prototyping, learning, experimenting... I see AI use as totally valid, as long as you’re being conscious, honest, and transparent. The rules of this jam even mention that.

Still, as devs, I think we should keep asking questions and thinking about how to build a space where these tools can exist ethically and fairly, helping everyone: artists, developers, and players.

The Development of Gatonauta: Racing the Clock

Back to development: during this period, I created the first planet assets, the character, some items, and resources, but nothing was functional yet. It wasn’t until around day seven that I finally managed to finish crucial systems like inventory and resource collection. By then, I had already scrapped several parts of my initial scope:

Survival: In the context of my idea, survival was just another layer. If the game core wasn’t even ready, that layer would only get in the way.
Combat: Sadly, combat systems weren’t going to happen with so little free time. Maybe next time.
Grappling Hook: This was scrapped along with space mining, but it would’ve been super cool to have.
Dialogues: I had a whole story planned involving the Gatonaut and his sidekick, CatGPT (the little drone that flies around breaking stuff).
Dungeons: Another idea dropped due to time constraints.

I focused on getting the basics working: movement, resource gathering, crafting, and building. Plus, the planet exploration part. I needed the game to at least have a complete gameplay loop. So I decided to go for a single simple goal: fix the spaceship. To do that, the player needs to craft three different parts. I planned the recipes for those parts and designed the steps to get them. Nothing overly complex, just enough to be fun for most players without requiring a grind.

I tried my best to make things modular using Godot’s signals, so the game would be easy to expand. In practice, if I wanted to add more resources, nodes, or structures, I just needed to create new instances using the existing logic, data, and textures.

All recipes, crafting, and upgrades are defined with simple dictionaries. Sometimes I use special objects for recipes, but they still rely on dictionaries under the hood:

## Structure costs dictionary
const STRUCTURE_COST: Dictionary[String, Dictionary] = {
    "FURNACE": {
        "COBBLESTONE": 10
    },
    "STORAGE": {
        "COBBLESTONE": 5,
        "WOOD": 5,
        "CHARCOAL": 5
    },
    "WORKBENCH": {
        "COBBLESTONE": 10,
        "WOOD": 5,
        "GEAR": 2
    },
    "3D_PRINTER": {
        "BAR": 10,
        "CHARCOAL": 5,
        "GEAR": 30
    },
}

## Structure prefab dictionary
const STRUCTURE_PREFAB: Dictionary[String, PackedScene] = {
    "FURNACE": preload("res://scenes/structures/furnace.tscn"),
    "3D_PRINTER": preload("res://scenes/structures/3d_printer.tscn"),
}

const STRUCTURE_RECIPES: Dictionary[String, Array] = {
    "FURNACE": [
        preload("res://scripts/data/recipes/charcoal.tres"),
        preload("res://scripts/data/recipes/bar.tres")
    ],
    "DAMAGED_SHIP": [
        preload("res://scripts/data/recipes/fix-ship.tres"),
    ],
    "3D_PRINTER": [
        preload("res://scripts/data/recipes/ship-piece-1.tres"),
        preload("res://scripts/data/recipes/ship-piece-2.tres"),
        preload("res://scripts/data/recipes/ship-piece-3.tres"),
    ]
}

const UPGRADES_RECIPES: Dictionary[String, Dictionary] = {
    "FIX_JETPACK": {
        "GEAR": 5
    },
    "PLANETOID_INDICATOR": {
        "WOOD": 5,
        "COBBLESTONE": 5,
        "CHARCOAL": 10,
    },
    "BETTER_JETPACK": {
        "CHARCOAL": 10,
        "COBBLESTONE": 10,
    },
    "FASTER_HARVEST": {
        "WOOD": 15,
        "COBBLESTONE": 15,
        "GEAR": 25
    },
    "MORE_RESOURCES": {
        "ORE": 20,
        "GEAR": 15
    }
}

I wish I had polished the UI more, but I realized that every time I added a new feature, I spent way too long finishing it. This made it clear how inexperienced I am with Godot’s UI system. So I decided to keep it simple but functional. No fancy icons or effects... just text. The goal was to make sure players understood what to do and how to do it, even if it wasn’t the prettiest.

I spent day nine testing and fixing bugs, prepared a credits screen, and wrapped up the game. On day ten, I had work, so I could only fix a few last-minute bugs.

Conclusion

Joining this jam was, without a doubt, an amazing experience. I learned so much, tried out ideas I had shelved for a long time, like planet gravity, continuous integration, and even using AI more seriously in my workflow.

Gatonauta ended up being far from what I originally dreamed, but that’s not necessarily a bad thing. Part of the process is understanding your limits, adjusting the scope, and turning a giant idea into something that’s functional, fun, and gets the concept across.

I definitely leave this jam even more motivated to keep developing games, improving my processes, understanding my strengths better, and, more importantly, my weaknesses.

If you made it this far, thank you so much for reading. I hope this post inspired you, helped you, or maybe even gave you that little push to join your first (or next) game jam.

And if you’d like to try the game, it’s available here:
Gatonauta by StealthC

[PT-BR] Gatonauta: Experiência do GameDev.tv GameJam 2025

StealthC — Wed, 28 May 2025 17:38:20 +0000

Tradução: This post is also available in English

Decidi participar da game jam da GameDev.tv (GameDev.tv Game Jam 2025 - Free Course For All Submissions! - itch.io), que é uma ótima opção para quem está começando no desenvolvimento de jogos. A comunidade é bem acolhedora, formada principalmente por alunos e iniciantes, e a troca de feedbacks é muito ativa e construtiva. Além disso, todo participante que enviar um jogo, automaticamente ganha um curso deles, que é algo muito bom pra quem está começando!

Essa é uma jam de 10 dias, e o tema escolhido foi “Tiny World”. No ano passado, participei com um jogo chamado Gataria by StealthC, feito para o tema “Last Stand”, e recebi muitos feedbacks positivos. Eu já sabia que queria fazer mais um jogo com um gato como protagonista, e, assim que o tema saiu, comecei a pensar em como encaixar essa ideia.

Dessa vez, decidi me arriscar com um escopo bem maior que Gataria, mesmo sabendo que corria o risco de não conseguir finalizar a tempo. Afinal, boa parte dos 10 dias eram dias úteis, e eu também precisava conciliar com meu trabalho.

Escolha de ferramentas e escopo inicial...

Minha proposta era criar um jogo de sobrevivência, exploração e crafting, com bastante inspiração em jogos como Factorio e Forager. Além disso, queria implementar uma mecânica de gravidade em pequenos planetas, no estilo Super Mario Galaxy, mas adaptado para um jogo 2D.

Decidi usar o Godot Engine (arrisquei e fiz todo na versão beta 4.5 dev3), que é uma ferramenta que já conheço bem e que me permite desenvolver jogos de forma rápida e eficiente. Suas builds para Web são ótimas e leves, perfeitas para game jams, e a comunidade é bem ativa, o que facilita encontrar soluções para problemas comuns.

Uma das coisas que eu não tinha feito antes, mas dessa vez decidi implementar, foi preparar uma CI (integração contínua) para o projeto, usando o GitHub. Assim, a cada commit que eu fizesse na branch main, o jogo seria compilado e disponibilizado automaticamente no Itch.io. Isso me ajudou a manter o controle do progresso, fazer outras pessoas testarem e identificar bugs mais rapidamente.

O workflow ficou assim (Se você quiser usar este workflow, lembre-se de adaptar as chaves e ajustar a versão do Godot conforme o seu projeto):

name: Export and Upload to Itch.io

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Export Godot project
        id: export
        uses: firebelley/godot-export@v6.0.0
        with:
          godot_executable_download_url: https://github.com/godotengine/godot-builds/releases/download/4.5-dev4/Godot_v4.5-dev4_linux.x86_64.zip
          godot_export_templates_download_url: https://github.com/godotengine/godot-builds/releases/download/4.5-dev4/Godot_v4.5-dev4_export_templates.tpz
          relative_project_path: ./
          archive_output: true
          cache: true

      - name: Upload to Itch.io
        uses: Ayowel/butler-to-itch@v1
        with:
          butler_key: ${{ secrets.ITCHIO_API_KEY }}
          itch_user: MEU_USUARIO_ITCHIO
          itch_game: NOME_DO_JOGO_ITCHIO
          version: ${{ github.ref_name }}
          files: ${{ steps.export.outputs.archive_directory }}/Web.zip

Um conceito bem ambicioso...

O meu conceito inicial já deixava claro que não seria uma tarefa fácil. Eu queria que o jogo tivesse:

Um sistema de sobrevivência, com fome e gerenciamento de recursos.
Combate e elementos de ação.
Dungeons, para exploração e desafios extras.
Um gancho, para se prender em asteroides ou puxar objetos até o personagem.
Internacionalização, para que o jogo pudesse ser jogado em português e inglês.

Com esse escopo, uma partida poderia demorar bastante. Então, seria necessário ter um sistema de salvamento. Comecei criando esse sistema, que me tomou praticamente o primeiro dia inteiro, além de dedicar tempo ao planejamento da estrutura geral do jogo.

Aqui vai meu sketch inicial do projeto e a versão gerada por IA:

Recriando toda a teoria da gravidade...

No segundo dia, parti para um dos maiores desafios técnicos: fazer um sistema de movimentação com gravidade em planetoides. A ideia parecia simples na teoria: basta fazer a gravidade sempre apontar para o centro do planeta. Na prática... foi bem mais trabalhoso do que parecia.

A solução que encontrei foi calcular todos os movimentos (andar, pular, gravidade) como se estivessem num plano cartesiano normal. Só no final dos cálculos é que eu rotacionava o movimento, alinhando para que ele ficasse na direção correta em relação ao planeta. Na minha opinião, ficou bem suave e intuitivo.

if is_on_floor():
    _local_velocity.x = input_x * current_planet.side_velocity
else:
    _local_velocity.x = lerp(_local_velocity.x, input_x * current_planet.side_velocity / 2.0, 0.1) # Suaviza o movimento lateral no ar
...

var gravity_center = current_planet.global_position
var direction_to_center = (gravity_center - global_position).normalized()

...

var target_rotation = direction_to_center.angle() - PI / 2.0 # -PI/2 para alinhar com a direção do planeta

...

var local_rotated = _local_velocity.rotated(target_rotation).normalized() * abs(_local_velocity.x) # Aplica a rotação do jogador à velocidade local
velocity = local_rotated # Atualiza a velocidade do jogador com a velocidade local rotacionada
velocity += _gravity_velocity.rotated(target_rotation) # Aplica a velocidade da gravidade
velocity += _jetpack_velocity.rotated(global_rotation) # Aplica a velocidade do jetpack rotacionada pela rotação do jogador
move_and_slide()

No jogo há basicamente dois modos de física:

Dentro de um planeta, onde é calculado a gravidade, movimentos laterais e etc.
No espaço, onde a câmera fica fixa, a gravidade é desligada, mas agora você pode girar o personagem e impulsioná-lo na direção que ele está.

Claro que surgiram problemas no caminho. Nas builds Web, por exemplo, a física começava a apresentar erros, provavelmente por conta da perda de precisão dos floats. Depois de muito quebrar a cabeça, descobri que usar colisão quadrada no personagem e circular no planeta resolvia vários desses problemas. Se o personagem usasse uma colisão do tipo cápsula ou redonda, acontecia um bug estranho: ele se movia mais rápido para um lado do que para o outro, e esse erro ia acumulando aos poucos, ficando cada vez pior.

A corrida contra o tempo e uso de IA

Nos cinco dias seguintes, minha rotina foi basicamente trabalhar o dia todo e só conseguir mexer no jogo bem tarde da noite, quando já estava exausto e com a cabeça pouco produtiva. Por isso, optei por focar na criação dos assets: sprites, planetas, itens, sons, músicas e afins.

E é aqui que entro em um tema meio polêmico: o uso de inteligência artificial na criação de assets para jogos.

Sem dúvida, esse é um assunto que gera bastante discussão na comunidade de desenvolvimento, e com razão. A IA se tornou uma ferramenta extremamente poderosa, principalmente para quem trabalha sozinho ou em equipes pequenas, como é o caso de muita gente em game jams. Quando o tempo é apertado e nem sempre temos habilidades em todas as áreas, como arte, música ou efeitos sonoros, ela acaba sendo uma aliada bem interessante.

No meu caso, eu não sou artista profissional. Produzir todos os assets do zero: sprites, efeitos sonoros, músicas, interfaces... dentro de poucos dias simplesmente, não seria viável. Então sim, recorri a ferramentas de IA para acelerar parte desse processo.

Mas acho essencial refletir sobre como e por que usar IA. Ela não deve ser encarada como um substituto da criatividade humana, pelo menos não nesse momento, mas sim como uma extensão dela. Usei IA para transformar ideias que eu já tinha em algo mais concreto, como rascunhos visuais, texturas e até sons. Mas, na prática, quase tudo exigiu bastante trabalho manual: ajustar, editar, retrabalhar e encaixar no estilo e na proposta do jogo.

A IA, nesse contexto, acaba sendo apenas mais uma ferramenta, assim como é, por exemplo, um gerador de efeitos sonoros como o jsfxr - 8 bit sound maker, que também usei no projeto. Ela resolve um problema prático, permitindo que uma ideia se transforme em algo jogável, sem que você trave nas partes onde não domina 100%.

Claro que eu também entendo, e concordo em vários pontos, com quem traz críticas. Existem preocupações bem válidas sobre como os modelos são treinados, muitas vezes usando trabalhos de artistas sem consentimento, e sobre como isso pode afetar o mercado criativo e desvalorizar o trabalho de profissionais.

Na minha opinião, boa parte dos problemas que vemos hoje não são causados exatamente pela IA em si, mas pela forma como todo o sistema foi estruturado. A concentração de tecnologia nas mãos de poucos, todo o modelo de negócios usado, tudo isso faz parte do problema. E esse debate, honestamente, vai muito além da tecnologia em si.

No contexto de uma game jam, que é um ambiente de aprendizado, prototipagem e experimentação, vejo o uso da IA como algo totalmente válido, desde que usado de forma consciente, honesta e transparente. Inclusive, isso é abordado nas próprias regras dessa jam específica.

Mas acho que, como desenvolvedores, é nosso papel continuar questionando e discutindo como construir um cenário onde essas ferramentas possam existir de forma mais justa, ética e equilibrada, beneficiando a todos, desde quem cria, quem desenvolve e quem joga.

O desenvolvimento do Gatonauta: Problemas de Prazo

Voltando ao desenvolvimento, nesse tempo eu criei os primeiros assets de planetas, do personagem, de alguns itens e recursos, mas nada ainda estava funcional. Foi só lá pelo sétimo dia que finalmente consegui concluir partes mais importantes, como o sistema de inventário e a coleta de recursos. Nesse tempo, eu já havia riscado várias partes do meu escopo inicial:

Survival: No caso do meu conceito, survival seria só mais uma camada do jogo. Se a base nem está completa, essa camada mais atrapalharia do que ajudaria.
Combate: infelizmente, fazer sistemas de combate com tão pouco tempo livre não iria rolar. Fica para a próxima.
Gancho: isso foi riscado com toda a parte de mineração no espaço, mas seria muito legal de ter.
Diálogos: cheguei a pensar em toda uma história envolvendo o Gatonauta e seu assistente, o GatoGPT (que é esse drone que fica destruindo as coisas).
Dungeons: outro plano riscado por falta de tempo.

Me concentrei em fazer o básico funcionar: movimentação, coleta de recursos, crafting e construção. E, claro, a parte de exploração com os planetas. Só que precisaria, pelo menos, ter um gameplay completo. Então decidi focar em um único objetivo simples: consertar a nave. Para isso, o jogador precisaria obter três peças diferentes. Planejei a receita dessas peças e os passos para obtê-las. Não quis deixar muito complexo, mas algo que fosse viável e divertido para a maioria dos jogadores, sem muito grind.

Tentei ao máximo abstrair e usar os signals do Godot para poder reutilizar as classes e fazer o jogo ser facilmente expansível, na prática, se eu quisesse criar mais recursos, nodes, ou estruturas, era só criar instâncias dos objetos existentes, com os novos dados e texturas.

Todas as receitas, crafting e upgrades usam dicionários simples para definição, algumas vezes, uso um tipo especial de objeto para as receitas, mas continua sendo baseado em dicionários:

## Dicionário de custos das estruturas
const STRUCTURE_COST: Dictionary[String, Dictionary] = {
    "FURNACE": {
        "COBBLESTONE": 10
    },
    "STORAGE": {
        "COBBLESTONE": 5,
        "WOOD": 5,
        "CHARCOAL": 5
    },
    "WORKBENCH": {
        "COBBLESTONE": 10,
        "WOOD": 5,
        "GEAR": 2
    },
    "3D_PRINTER": {
        "BAR": 10,
        "CHARCOAL": 5,
        "GEAR": 30
    },
}

## Dicionário de prefabs das estruturas
const STRUCTURE_PREFAB: Dictionary[String, PackedScene] = {
    "FURNACE": preload("res://scenes/structures/furnace.tscn"),
    "3D_PRINTER": preload("res://scenes/structures/3d_printer.tscn"),
}

const STRUCTURE_RECIPES: Dictionary[String, Array] = {
    "FURNACE": [
        preload("res://scripts/data/recipes/charcoal.tres"),
        preload("res://scripts/data/recipes/bar.tres")
    ],
    "DAMAGED_SHIP": [
        preload("res://scripts/data/recipes/fix-ship.tres"),
    ],
    "3D_PRINTER": [
        preload("res://scripts/data/recipes/ship-piece-1.tres"),
        preload("res://scripts/data/recipes/ship-piece-2.tres"),
        preload("res://scripts/data/recipes/ship-piece-3.tres"),
    ]
}

const UPGRADES_RECIPES: Dictionary[String, Dictionary] = {
    "FIX_JETPACK": {
        "GEAR": 5
    },
    "PLANETOID_INDICATOR": {
        "WOOD": 5,
        "COBBLESTONE": 5,
        "CHARCOAL": 10,
    },
    "BETTER_JETPACK": {
        "CHARCOAL": 10,
        "COBBLESTONE": 10,
    },
    "FASTER_HARVEST": {
        "WOOD": 15,
        "COBBLESTONE": 15,
        "GEAR": 25
    },
    "MORE_RESOURCES": {
        "ORE": 20,
        "GEAR": 15
    }
}

Eu gostaria de ter polido mais a UI, mas percebi que, a cada nova feature, eu demorava muito para finalizar. Isso deixou clara minha falta de experiência com a UI do Godot. Então decidi deixar a UI mais simples, mas funcional. Nada de ícones ou efeitos, só texto. A ideia era que o jogador conseguisse entender o que fazer e como fazer, mesmo que não fosse tão bonito.

Gastei o nono dia testando e resolvendo bugs, preparei uma tela de créditos e finalizei o jogo. No décimo dia, eu tinha trabalho, então só consegui ajustar pequenos bugs que escaparam.

Conclusão

Participar dessa jam foi, sem dúvidas, uma experiência incrível. Além de aprender muita coisa nova, pude testar ideias que estavam na gaveta há tempos, como o sistema de gravidade em planetas, integração contínua e até experimentar o uso de IA de forma mais consistente no desenvolvimento.

O Gatonauta ficou longe de tudo que sonhei no início, mas isso não é necessariamente algo ruim. Faz parte do processo entender os próprios limites, ajustar o escopo e transformar uma ideia gigante em algo que, pelo menos, funcione, seja divertido e transmita uma proposta.

Com certeza saio dessa jam com ainda mais vontade de continuar desenvolvendo, melhorar meus processos, entender melhor meus pontos fortes e, principalmente, meus pontos fracos.

Se você leu até aqui, muito obrigado. Espero que esse relato tenha te inspirado, ajudado ou, quem sabe, te dado aquele empurrãozinho para participar da sua primeira (ou próxima) game jam.

E se quiser jogar o jogo, ele está disponível em:
Gatonauta by StealthC

[EN] Introduction to Frida: Real-Time Memory Manipulation with TypeScript (and DOOM)

StealthC — Wed, 11 Dec 2024 00:59:52 +0000

Translation: Este artigo também está disponível em Português

Introduction

The other day, I was reading updates on the website of a tool I follow called Frida, which is, as they describe it, a "Greasemonkey for native programs." In other words, it’s a toolkit with its own API to analyze, interact, and manipulate running programs, supporting multiple platforms.

Anyway, I came across this September 2024 update that not only announced some new features but also showcased an interesting use case. It involved the game "Doom + Doom II," which was released recently. In the example, they demonstrated a tool that scans memory to locate where the ammo count is stored and, with remarkable ease, creates a sort of Cheat Engine to maintain infinite ammo. I loved how practical this example was and decided to recreate it while detailing every step here.

Installing Frida

As I mentioned earlier, Frida is available for multiple platforms. Here, I’m using Windows and already have Python installed, so I’ll simplify the installation process by using pip:

pip install frida-tools

Usage Example

The frida-tools package comes with several utilities to interact with the Frida ecosystem (you can learn more by visiting the official documentation).

A practical example is using frida to attach directly to a running program. For instance:

frida -n CalculatorApp.exe

This opens Frida and attaches it to the process called CalculatorApp.exe, which is the Windows calculator.

From this new prompt, you can use several built-in functions and call JavaScript directly to access the application’s memory, registers, interrupts, etc.

It’s great for quick tests, but the real power comes from creating your own scripts, known as "agents."

Choosing the API Language

You can write these agent scripts in various languages. Frida offers support for Python, JavaScript, C, Go, Swift, and others.

For this example, I’ll go with JavaScript—or even better, TypeScript, which provides autocomplete and quick access to documentation, as shown below:

Documentation and autocomplete—some of the best things about modern IDEs (until AI came along)

Setting Up the Project Structure

Frida’s documentation for JavaScript suggests cloning the following repository to start developing your "agent": (https://github.com/oleavr/frida-agent-example). So, I’ll clone it, install the dependencies, and open it in VS Code:

git clone https://github.com/oleavr/frida-agent-example.git doom_example
cd .\doom_example\
npm install
code .

The repository simplifies programming in TypeScript and compiling JavaScript to be used by Frida. It comes with some scripts in package.json, like pnpm watch, which watches and compiles the ./agent/index.ts file automatically.

However, in the latest versions of Frida, it can directly read our TypeScript, so we don’t need to compile to .js.

One More Thing Before We Continue

It’s likely, as was the case during my tests, that the repository has some outdated dependencies. Don’t forget to run npm update --save to update the dependencies, especially the typings.

Basic Agent

Let’s start with the same example from the original post, adding some comments, typings, and adapting it for TypeScript:

Important note: If you use plain JavaScript for the agent, you can directly call any function or variable declared in the script. However, when using TypeScript, functions and variables are not added to the global object. You must export them to the globalThis object. I’m making this export at the end of the script.

let matches: NativePointer[] = [];

// Scans the process memory for a pattern
function scan(pattern: string | MatchPattern) {
  const locations = new Set<string>();
  for (const r of Process.enumerateMallocRanges()) {
    for (const match of Memory.scanSync(r.base, r.size, pattern)) {
      locations.add(match.address.toString());
    }
  }
  matches = Array.from(locations).map(ptr);
  console.log('Found', matches.length, 'matches');
}

// Further filters results for those containing a specific value
function reduce(val: number) {
  matches = matches.filter(location => location.readU32() === val);
  console.log('Filtered down to:');
  console.log(JSON.stringify(matches));
}

// Converts a numeric value into a pattern for a 32-bit unsigned integer
function patternFromU32(val: number) {
  return new MatchPattern(ptr(val).toMatchPattern().slice(0, 11));
}

globalThis['scan'] = scan;
globalThis['reduce'] = reduce;
globalThis['patternFromU32'] = patternFromU32;

Attaching Frida to the Game

Now, let’s run Frida and attach it to the game.

frida -n doom_gog.exe -l agent/index.ts

Make sure the game is running so frida can locate the process using the -n option. If you’re unsure about the process name, use frida-ps to list all running processes.

Finding a Value in Memory (a needle in a haystack)

In the original post, the author searches for the memory location where the ammo count is stored. But let’s switch things up and look for where our health (or "HP," "life," or whatever you call it) is stored.

Let’s hope this 100% is an integer...

In the open Frida console, we’ll execute our scan function with a pattern for the number 100 as an argument.

[Local::doom_gog.exe ]-> scan(patternFromU32(100))
Found 8073 matches

Whoa, 8073 matches for the number 100! That seems like a lot, but not too bad. We need to narrow it down. First, let’s take some damage in the game:

Take that, barrel filled with mysterious green liquid!

Now that our health has dropped to 67%, let’s further filter our results using the reduce function we created in the script:

[Local::doom_gog.exe ]-> reduce(67)
Filtered down to:
["0x179b96a0d0c","0x179f5499984"]`

We’re left with two possibilities. Which one is it? Hang on, I’ll figure it out…

Drinking this blue potion I found on the ground...

Now that our health is at 68%, let’s filter the results again:

[Local::doom_gog.exe ]-> reduce(68)
Filtered down to:
["0x179b96a0d0c","0x179f5499984"]

Hmm, we still have two addresses left. It’s possible that health is stored in two different memory locations or represents two separate update states. Maybe I shouldn’t have tested this by both losing and then regaining health, but oh well—let’s move on with the experiment.

Creating Dynamic Watchpoints

Let’s proceed with the article by creating a helper function to set watchpoints. This function will take the memory address, the size of the stored data, and the break condition type as arguments. We’ll use w to specify that it should only trigger on write conditions.

Don’t forget to register the function with globalThis at the end.

function installWatchpoint(address: NativePointerValue, size: number | UInt64, conditions: HardwareWatchpointConditions) {
    const thread = Process.enumerateThreads()[0];

    Process.setExceptionHandler(e => {
      console.log(`\n=== Handler got ${e.type} exception at ${e.context.pc}`);

      if (Process.getCurrentThreadId() === thread.id &&
          ['breakpoint', 'single-step'].includes(e.type)) {
        thread.unsetHardwareWatchpoint(0);
        console.log('\tDisabled hardware watchpoint');
        return true;
      }

      console.log('\tPassing to application');
      return false;
    });

    thread.setHardwareWatchpoint(0, address, size, conditions);

    console.log('Ready');
}

globalThis['installWatchpoint'] = installWatchpoint;

Identifying the Code Location (via Watchpoints)

Now the goal is to find where in the game’s code the damage calculation is executed. Let’s start by registering a watchpoint for the first address:

[Local::doom_gog.exe ]-> installWatchpoint(ptr('0x179b96a0d0c'), 4, 'w')
Ready

After inserting the watchpoint, I tried taking more damage, but nothing happened. However, when I picked up a potion, the code was triggered:

[Local::doom_gog.exe ]->
=== Handler got single-step exception at 0x7ff6332f7b08
        Disabled hardware watchpoint

This indicates that the first address we located is likely used in the context of health recovery. Since we’re more interested in the damage context, I tested the other address. This time it triggered when I took damage in the game:

[Local::doom_gog.exe ]-> installWatchpoint(ptr('0x179f5499984'), 4, 'w')
Ready
[Local::doom_gog.exe ]->
=== Handler got single-step exception at 0x7ff6332fafcc
        Disabled hardware watchpoint

Finding the Exact Code Execution Location

With the address where the value change occurs, 0x179f5499984, let’s find its relative offset to the program’s base.

[Local::doom_gog.exe ]-> healthCode = ptr('0x7ff6332fafcc')
"0x7ff6332fafcc"
[Local::doom_gog.exe ]-> healthModule = Process.getModuleByAddress(healthCode)
{
    "base": "0x7ff633020000",
    "name": "doom_gog.exe",
    "path": "F:\\GOG Games\\DOOM + DOOM II\\doom_gog.exe",
    "size": 15450112
}
[Local::doom_gog.exe ]-> offset = healthCode.sub(healthModule.base)
"0x2dafcc"

Now we know the address is in the doom_gog.exe module and its position relative to the program’s base is 0x2dafcc.

Checking the Address in a Disassembler

We can use any debugger with disassembler support to analyze this segment and determine its functionality. You can use tools like radare2, IDA, or GHidra. In this example, I used x64dbg and navigated to the correct address by pressing Ctrl+G and entering the expression:

doom_gog.exe+0x2dafcc

... which produced the following disassembly:

Here, we see the instruction executed immediately after the health value decreases. We can hypothesize that [rsi+24] holds our health value and r15d represents the damage received. Let’s focus on the damage received for now.

Creating Interceptors to Dynamically Receive Data

Following the example from the original article, let’s create an interceptor for this instruction to capture the amount of damage received.

Since this function is executed directly in the script, we don’t need to add it to globalThis.

Interceptor.attach(Module.getBaseAddress('doom_gog.exe').add(0x2dafcc), function () {
    const context = this.context as X64CpuContext;
    const damageReceived = context.r15;
    console.log(`Damage Received: ${damageReceived}`);
});

After saving the script, if we continue to take damage in the game, the Frida console will print messages showing the amount of damage:

Now, the Ultimate Manipulation!

If we want, as in the original example, to completely ignore the damage, we just need to move the interceptor to the previous instruction (address 0x2dafc8) and dynamically set the register value to zero!

Interceptor.attach(Module.getBaseAddress('doom_gog.exe').add(0x2dafc8), function () {
    const context = this.context as X64CpuContext;
    const damageReceived = context.r15;
    console.log(`Damage Received: ${damageReceived.toUInt32()}, but we will just ignore it`);
    context.r15 = ptr(0);
});

Who needs IDDQD?

Conclusion

This exercise was fantastic for exploring what a tool like Frida can offer. This dynamic way of handling data is also incredibly interesting for learners. The example with Doom was perfect due to its simplicity. Keep in mind that creating a game cheat like this is merely "scratching the surface" of possibilities. Tools like Frida can—and should—be extensively used for tasks like malware analysis, software behavior studies, security assessments, and more.

[PT-BR] Introdução ao Frida: Como Manipular Memória em Tempo Real com TypeScript (e DOOM)

StealthC — Wed, 11 Dec 2024 00:47:11 +0000

Tradução: This post is also available in English

Introdução

Outro dia eu estava lendo as notícias do site de uma ferramenta que eu acompanho, chamado Frida que é, como eles mesmo dizem no site, um Greasemonkey para programas nativos, ou seja, é um kit de ferramentas com uma API própria que ajuda a analisar, interagir e manipular programas em execução com suporte para várias plataformas diferentes.

Mas enfim, me deparei com essa notícia de setembro de 2024 que, além de informar novidades no projeto, demonstra uma utilização bastante interessante. Usa como base, o jogo "Doom + Doom II", que foi lançado a pouco tempo. No exemplo, ele cria uma ferramenta que busca na memória, onde número de munição é armazenado e com muita facilidade, cria uma espécie de Cheat Engine para manter as balas infinitas. Eu adorei a praticidade do exemplo e resolvi refazê-lo, mas detalhando aqui cada etapa.

Instalando o Frida

Como eu disse no início, o Frida está disponível para várias plataformas. Aqui, estou usando o Windows e já tenho o python instalado, então vou simplificar o processo de instalação usando o pip:

pip install frida-tools

Exemplo de utilização

O pacote frida-tools vem com vários utilitários para trabalhar com o ecossistema do Frida (Você pode saber mais sobre eles visitando a documentação oficial).

Porém, um exemplo bem prático é usar o frida para anexar-se diretamente em um programa em execução, por exemplo:

frida -n CalculatorApp.exe

Vai abrir o frida e se anexar no processo chamado CalculatorApp.exe, que é a calculadora do windows.

A partir desse novo prompt, você pode usar diversas funções embutidas e chamar JavaScript diretamente para acessar a memória do aplicativo, registros, interrupções, etc.

É ótimo para fazer testes rápidos, mas o melhor mesmo é fazer seus próprios scripts, os chamados "agentes".

Escolhendo a linguagem da API

Você pode escrever esses scripts de agentes em várias linguagens diferentes, o Frida oferece já suporte para linguagens como Python, JavaScript, C, Go e Swift, dentre outras.

Neste meu exemplo, vou de JavaScript, ou melhor ainda, TypeScript, que oferece algum suporte para autocompletar e verificar rapidamente a documentação, conforme mostrado abaixo:

Documentação e autocompletar, as melhores coisas de IDE modernos (até a chegada das IAs)

Preparando a estrutura do projeto

A documentação do Frida sobre JavaScript sugere clonar o seguinte repositório para começar a desenvolver seu "agente": (https://github.com/oleavr/frida-agent-example), então vou clonar ele, instalar as dependências e abrir no VS Code:

git clone https://github.com/oleavr/frida-agent-example.git doom_example
cd .\doom_example\
npm install
code .

A ideia do repositório é simplificar a tarefa de programar em TypeScripte compilar o JavaScript para ser usado pelo Frida, ele vem com alguns scripts no package.json, como npm watch que observa e compila automaticamente o arquivo ./agent/index.ts.

Porém, nas últimas versões do Frida, ele consegue ler automaticamente nosso TypeScript, então não precisamos compilar o .js.

Mais uma coisa antes de seguirmos

É bem provável, como foi o caso quando eu estava testando, que o repositório esteja com algumas dependências já ultrapassadas, não esqueça de rodar npm update --save para atualizar as dependências, principalmente as tipagens.

Agente básico

Vamos começar usando o mesmo exemplo da postagem original, adicionando alguns comentários, inserindo tipagens e adaptando para o TypeScript:

Uma observação importante: Se você usar JavaScript puro para fazer o agente, poderá chamar diretamente qualquer função ou variável declarada no script. Porém, ao usar TypeScript, as funções e variáveis não são inseridas no objeto global e portanto, você não conseguirá acessá-las diretamente a menos as exporte para o objeto globalThis. Estou fazendo essa exportação logo no fim do script.

let matches: NativePointer[] = [];

// Escaneia a memória do processo em busca de um padrão
function scan(pattern: string | MatchPattern) {
  const locations = new Set<string>();
  for (const r of Process.enumerateMallocRanges()) {
    for (const match of Memory.scanSync(r.base, r.size, pattern)) {
      locations.add(match.address.toString());
    }
  }
  matches = Array.from(locations).map(ptr);
  console.log('Found', matches.length, 'matches');
}

// Filtra ainda mais os resultados para aqueles que contém um valor específico
function reduce(val: number) {
  matches = matches.filter(location => location.readU32() === val);
  console.log('Filtered down to:');
  console.log(JSON.stringify(matches));
}

// Converte um valor numérico em um padrão para número inteiro unsigened de 32 bits
function patternFromU32(val: number) {
  return new MatchPattern(ptr(val).toMatchPattern().slice(0, 11));
}

globalThis['scan'] = scan;
globalThis['reduce'] = reduce;
globalThis['patternFromU32'] = patternFromU32;

Anexando o Frida ao jogo

Agora rodamos o Frida e anexamos ao jogo.

frida -n doom_gog.exe -l agent/index.ts

Você deve estar com o jogo em execução para que o frida possa encontrar o processo usando a opção -n, se você tiver dúvidas sobre o nome do processo, use o frida-ps para listar todos os processos em execução.

Encontrando um valor na memória (uma palha em um agulheiro)

Na postagem original, o autor busca na memória o local onde o valor da munição é armazenado, mas vamos tentar diferente e procurar onde está nossa vida (ou "saúde", "life", "HP", ou como você gostar de chamar)

Vamos torcer para que esse 100% seja um número inteiro…

No console aberto do frida, vamos executar nossa função scan com um padrão do número 100 criado como argumento.

[Local::doom_gog.exe ]-> scan(patternFromU32(100))
Found 8073 matches`

Eita, 8073 resultados para o número 100, isso parece muito, mas nem tanto, precisamos diminuir as possibilidades, para isso, vamos primeiro sofrer algum dano no jogo:

Tome isto, barril com líquido verde estranho!

Agora que reduzimos nossa vida para 67%, vamos filtrar ainda mais nossa busca usando a função criada no script reduce:

[Local::doom_gog.exe ]-> reduce(67)
Filtered down to:
["0x179b96a0d0c","0x179f5499984"]`

Ainda sobraram duas possibilidades, qual será? Espera, que já resolvo isso…

Bebendo desse frasco azul que encontrei no chão…

Agora que estamos com 68% de vida, vamos filtrar novamente:

[Local::doom_gog.exe ]-> reduce(68)
Filtered down to:
["0x179b96a0d0c","0x179f5499984"]`

Ué, continuamos com os dois endereços... É provável que a vida esteja mesmo sendo armazenada em dois locais diferentes na memória ou ainda podem ser estados diferentes de atualização. Talvez eu não devesse ter testado sofrendo e depois recuperando vida, mas enfim, vamos seguir com a experiência...

Criando watchpoints dinamicamente

Vamos continuar com o artigo e criar uma função helper para designar watchpoints. Essa função vai receber como argumentos, o endereço da memória, o tamanho do dado armazenado e o tipo de condição para o break, que posteriormente vamos usar w para dizer para ele parar apenas em condições de write, ou seja, de escrita.
Não se esqueça de registrar a função no globalThis, no final.

function installWatchpoint(address: NativePointerValue, size: number | UInt64, conditions: HardwareWatchpointConditions) {
    const thread = Process.enumerateThreads()[0];

    Process.setExceptionHandler(e => {
      console.log(`\n=== Handler got ${e.type} exception at ${e.context.pc}`);

      if (Process.getCurrentThreadId() === thread.id &&
          ['breakpoint', 'single-step'].includes(e.type)) {
        thread.unsetHardwareWatchpoint(0);
        console.log('\tDisabled hardware watchpoint');
        return true;
      }

      console.log('\tPassing to application');
      return false;
    });

    thread.setHardwareWatchpoint(0, address, size, conditions);

    console.log('Ready');
  }

globalThis['installWatchpoint'] = installWatchpoint;

Obtendo a localização do código (via watchpoints)

O objetivo agora é obter onde no código do jogo, o dano é executado. Então vamos começar registrando o watchpoint do primeiro endereço:

[Local::doom_gog.exe ]-> installWatchpoint(ptr('0x179b96a0d0c'), 4, 'w')
Ready

Após inserir o watchpoint, tentei sofrer mais dano, porém nada aconteceu. Mas aí, ao pegar uma poção, o código é executado:

[Local::doom_gog.exe ]->
=== Handler got single-step exception at 0x7ff6332f7b08
        Disabled hardware watchpoint

Ou seja, esse primeiro endereço, endereço que localizamos provavelmente é usado no contexto de recuperação de vida.
Estamos mais interessados no contexto de dano sofrido, então, testei com o outro endereço e dessa vez sim ele ativou quando eu tomei dano no jogo:

[Local::doom_gog.exe ]-> installWatchpoint(ptr('0x179f5499984'), 4, 'w')
Ready
[Local::doom_gog.exe ]->
=== Handler got single-step exception at 0x7ff6332fafcc
        Disabled hardware watchpoint

Obtendo a localização exata da execução do código

De posse do endereço onde a mudança do valor ocorre 0x7ff6332fafcc, vamos obter o endereço relativo à base do programa.

[Local::doom_gog.exe ]-> healthCode = ptr('0x7ff6332fafcc')
"0x7ff6332fafcc"
[Local::doom_gog.exe ]-> healthModule = Process.getModuleByAddress(healthCode)
{
    "base": "0x7ff633020000",
    "name": "doom_gog.exe",
    "path": "F:\\GOG Games\\DOOM + DOOM II\\doom_gog.exe",
    "size": 15450112
}
[Local::doom_gog.exe ]-> offset = healthCode.sub(healthModule.base)
"0x2dafcc"

Agora sabemos que o endereço está no módulo doom_gog.exe e que sua posição relativa à base do programa é 0x2dafcc

Conferindo o endereço em um disassembler

Podemos usar algum debugger com suporte a disasm para ver esse trecho e definir sua funcionalidade, você pode usar qualquer tipo de ferramenta: radare2, ida, GHidra, nesse exemplo eu abri com o x64dbg, e fui para o endereço correto pressionando Ctrl+G e inserindo a expressão:

doom_gog.exe+0x2dafcc

... que resultou no disasm abaixo:

Aqui, nós temos a instrução que é executada exatamente depois do valor da vida ter diminuído, imaginamos então que [rsi+24] é o nosso valor de vida e r15d é o dano recebido. Vamos nos concentrar no dano recebido por enquanto...

Criando interceptadores para receber dados dinamicamente

Seguindo o exemplo do artigo original, vamos criar um Interceptador para essa instrução, que vai nos dizer a quantidade de dano recebido.

Como essa função é executada diretamente no script, não precisamos adicionar ao globalThis.

Interceptor.attach(Module.getBaseAddress('doom_gog.exe').add(0x2dafcc), function () {
    const context = this.context as X64CpuContext;
    const damageReceived = context.r15;
    console.log(`Damage Received: ${damageReceived}`);
});

Logo depois de salvar o script, se continuarmos a receber dano no jogo, o console do frida irá imprimir mensagens informando a quantidade de dano:

E agora, a manipulação suprema!

Se quisermos, igual ao exemplo original, que o dano seja totalmente ignorado, basta trazer o interceptador para a instrução anterior (endereço 0x2dafc8) e substituir dinamicamente o valor de registro para zero!

Interceptor.attach(Module.getBaseAddress('doom_gog.exe').add(0x2dafc8), function () {
    const context = this.context as X64CpuContext;
    const damageReceived = context.r15;
    console.log(`Damage Received: ${damageReceived.toUInt32()}, but we will just ignore it`);
    context.r15 = ptr(0);
});

Pra que o IDDQD?

Conclusão

Esse exercício foi ótimo para testar o que uma ferramenta como o Frida pode oferecer, essa forma dinâmica de lidar com os dados é muito interessante também para quem está aprendendo, e o exemplo com o Doom foi muito bem-vindo pela simplicidade. Note que ao fazer um cheat de um jogo, estamos apenas "arranhando" a superfície das possibilidades, ferramentas como o Frida podem e devem ser amplamente utilizadas para auxilio e simplificação de análise de malware, estudo de comportamento de software, segurança e outros processos.