DEV Community: Stefhany Santos

Primeiros passos com FiveM: Nativos, Frameworks e meu primeiro ensure

Stefhany Santos — Tue, 02 Jun 2026 15:34:17 +0000

Recentemente comecei meus estudos em desenvolvimento para servidores FiveM, com foco em bases como vRPex e Creative, que são bastante utilizadas no cenário brasileiro de servidores de roleplay.

Como venho do desenvolvimento Front-End, principalmente trabalhando com interfaces, componentização e integração com APIs, decidi documentar meus estudos para organizar melhor o aprendizado e também compartilhar minha evolução.

Neste primeiro artigo, vou registrar os principais pontos da minha primeira aula: nativos, frameworks e a estrutura inicial de um resource no FiveM.

O que é FiveM?

O FiveM é uma plataforma que permite criar servidores modificados para GTA V, possibilitando experiências personalizadas como servidores de roleplay, sistemas de empregos, economia, facções, lojas, garagens, inventários, interfaces e muito mais.

Dentro do FiveM, o desenvolvimento pode envolver várias linguagens e tecnologias, como:

Lua;
JavaScript;
HTML;
CSS;
MySQL;
frameworks específicos para RP;
interfaces NUI.

No meu caso, estou começando pela base mais comum em muitos servidores brasileiros: Lua + vRPex/Creative.

Nativos no FiveM

Na aula, entendi que existem códigos chamados de nativos.

Os nativos são funções fornecidas pelo próprio ambiente do FiveM/GTA, permitindo interagir diretamente com elementos do jogo.

Com eles, é possível fazer coisas como:

criar blips no mapa;
desenhar markers;
pegar coordenadas do player;
manipular veículos;
detectar ações do jogador;
criar threads;
interagir com entidades do mundo do GTA.

Um exemplo simples de estrutura usando Lua seria:

CreateThread(function()
    while true do
        Wait(1000)
        print("Thread rodando")
    end
end)

Essa estrutura mostra uma thread sendo executada continuamente, com uma pausa de 1 segundo entre cada execução.

O que é Citizen?

Durante a aula também apareceu o conceito de Citizen.

De forma simples, entendi o Citizen como uma biblioteca/base principal usada pelo FiveM para fornecer vários códigos nativos.

Ele ajuda o script a conversar com o ambiente do jogo, permitindo executar ações dentro do GTA V através do FiveM.

Porém, o Citizen sozinho não entrega toda a estrutura necessária para criar uma cidade RP completa.

Por exemplo, ele não resolve sozinho coisas como:

sistema de identidade;
inventário;
permissões;
whitelist;
economia;
conexão organizada com banco de dados;
empregos;
grupos;
comandos administrativos.

Para isso, normalmente usamos um framework.

O que é um framework no FiveM?

Um framework é uma estrutura de código que organiza e facilita o desenvolvimento de uma cidade RP.

Ele usa os nativos do FiveM e cria uma camada mais prática para lidar com sistemas comuns de roleplay.

Alguns exemplos de frameworks conhecidos são:

vRP;
vRPex;
Creative;
ESX;
QBCore;
Qbox.

No curso que estou fazendo, o foco será em vRP, principalmente em bases como vRPex e Creative.

O framework ajuda a padronizar coisas como:

pegar o usuário do jogador;
validar permissões;
trabalhar com inventário;
controlar dinheiro;
acessar dados do player;
criar comandos;
integrar sistemas com banco de dados.

Nativo vs Framework

Uma forma simples que encontrei para entender a diferença:

Conceito	Explicação
Nativo	Função mais próxima do FiveM/GTA
Framework	Estrutura que organiza sistemas de RP
Resource	Um script/módulo dentro do servidor
Ensure	Comando usado para iniciar um resource

Exemplo prático:

O nativo pode ser usado para desenhar um marker no mapa.

O framework pode ser usado para verificar se o jogador tem permissão para acessar aquele marker.

O resource organiza esse sistema em arquivos.

O ensure inicia esse resource no servidor.

O que é um resource?

No FiveM, os scripts são organizados em módulos chamados resources.

Cada resource pode representar um sistema da cidade, como:

banco;
garagem;
inventário;
loja de carros;
loja VIP;
HUD;
celular;
sistema de empregos;
sistema de facções;
painel administrativo.

Um resource normalmente possui uma estrutura parecida com esta:

meu_resource/
│
├── fxmanifest.lua
├── client.lua
├── server.lua
├── config.lua
└── html/
    ├── index.html
    ├── style.css
    └── script.js

O que é o `fxmanifest.lua`?

O fxmanifest.lua é o arquivo que registra o resource no FiveM.

É nele que informamos quais arquivos fazem parte do script e o que deve ser carregado no client, no server ou na interface.

Exemplo básico:

fx_version 'cerulean'
game 'gta5'

author 'Meu Nome'
description 'Meu primeiro resource FiveM'
version '1.0.0'

client_script 'client.lua'
server_script 'server.lua'
shared_script 'config.lua'

Esse arquivo é essencial para que o FiveM entenda como carregar o resource.

O que é `ensure`?

Depois de criar um resource, precisamos iniciar ele no servidor.

Para isso usamos o comando ensure.

Exemplo:

ensure meu_resource

Esse comando normalmente fica no arquivo de configuração do servidor.

Ele diz ao servidor:

“Carregue esse resource quando a cidade iniciar.”

Client e Server no FiveM

Um dos pontos mais importantes da aula foi entender a diferença entre client e server.

Client

O client.lua roda no lado do jogador, ou seja, na máquina de quem está jogando.

Ele normalmente lida com coisas visuais e interações locais, como:

criar blips;
desenhar markers;
detectar teclas pressionadas;
abrir interfaces;
pegar coordenadas;
executar animações;
mostrar informações na tela.

Server

O server.lua roda no lado do servidor.

Ele deve cuidar das partes mais importantes e sensíveis, como:

validar dinheiro;
validar permissões;
conferir itens;
salvar dados;
buscar dados no banco;
registrar logs;
aplicar regras do sistema.

Uma regra importante que já aprendi:

Nunca confiar totalmente no client.

Tudo que envolve dinheiro, item, permissão ou dado importante precisa ser validado no server.

Onde entra a NUI?

Como venho do Front-End, essa parte chamou bastante minha atenção.

No FiveM, a NUI é a interface visual de um sistema.

Ela pode ser feita com tecnologias como:

HTML;
CSS;
JavaScript;
React;
Vue;
jQuery.

A NUI seria como o “front-end” de um script.

Ela pode ser usada em sistemas como:

banco;
garagem;
loja de carros;
inventário;
HUD;
celular;
painel administrativo;
tablet policial;
loja VIP.

Um fluxo simples seria:

NUI / Interface
      ↓
Client.lua
      ↓
Server.lua
      ↓
Banco de dados

Ou seja, o jogador interage com a interface, a interface conversa com o client, o client chama o server e o server valida ou salva as informações.

Banco de dados

O servidor também pode se comunicar com banco de dados, geralmente MySQL.

O banco é usado para salvar informações como:

jogadores;
veículos;
dinheiro;
casas;
inventário;
empregos;
facções;
multas;
histórico de ações.

O fluxo correto é:

Client → Server → Banco de Dados

O client não deve acessar o banco diretamente.

Comparando com desenvolvimento web

Como venho do Front-End, fiz essa comparação para entender melhor:

Desenvolvimento Web	FiveM
Front-End	NUI
Back-End	Server.lua
Service/API call	Eventos client/server
Banco de dados	MySQL
Configuração	Config.lua
Módulo/projeto	Resource
Start do projeto	Ensure
Framework back-end	vRPex/Creative/QBCore/Qbox

Essa comparação me ajudou bastante a entender que o FiveM também tem uma separação de responsabilidades.

A diferença é que tudo acontece dentro do contexto do jogo.

Resumo da aula

Nesta primeira aula, aprendi que:

o FiveM usa nativos para interagir com o GTA;
o Citizen fornece várias funções base para o ambiente FiveM;
frameworks como vRPex e Creative organizam sistemas de roleplay;
cada script é estruturado como um resource;
o fxmanifest.lua registra o resource;
o ensure inicia o resource no servidor;
o client.lua roda na máquina do jogador;
o server.lua roda no servidor;
a NUI representa a interface visual;
o banco de dados deve ser acessado pelo server;
validações importantes devem ficar no servidor.

Próximo passo

Meu próximo objetivo é criar meu primeiro resource simples com:

fxmanifest.lua;
client.lua;
server.lua;
config.lua.

Quero praticar:

iniciar o resource com ensure;
criar um comando simples;
enviar evento do client para o server;
imprimir mensagens no console;
entender melhor a comunicação client/server.

Conclusão

Essa primeira aula foi importante para entender a base do desenvolvimento FiveM.

Mesmo sendo um ambiente diferente do desenvolvimento web tradicional, consegui perceber várias conexões com o que já conheço como Front-End.

Principalmente na parte de NUI, onde posso aplicar conhecimentos de interface, experiência do usuário e integração com lógica de sistema.

A ideia agora é continuar estudando Lua, vRPex, MySQL e NUI para começar a criar sistemas próprios para servidores de roleplay.

Este artigo é o primeiro registro da minha jornada estudando desenvolvimento para FiveM.

Como rodar seu Front-end no PC pessoal e o Backend (.NET) na máquina da empresa usando Ngrok

Stefhany Santos — Fri, 27 Feb 2026 09:21:18 +0000

Se você trabalha com desenvolvimento, talvez já tenha passado por esta situação:

Você tem um PC pessoal super rápido, mas precisa usar a máquina corporativa (normalmente mais lenta) por causa da VPN para acessar o banco de dados da empresa.

Trabalhar no Front-end com a máquina travando acaba com qualquer produtividade.

A solução?

Rodar o Backend na máquina da empresa e o Front-end no seu PC pessoal, usando o Ngrok para criar um túnel seguro entre os dois.

Mas, se o seu Backend for em .NET, você vai perceber que rodar um simples comando do Ngrok não funciona de primeira.

Neste artigo, vou te mostrar o pulo do gato para resolver isso.

1️⃣ Autenticando o Ngrok

Antes de tudo, baixe o Ngrok e adicione seu Authtoken.

Você encontra esse comando no painel do Ngrok, logo na tela inicial.

Depois, basta rodar o comando no terminal:

ngrok config add-authtoken SEU_TOKEN_AQUI

Isso vincula sua máquina à sua conta.

2️⃣ O Problema com .NET e Ngrok

Por padrão, aplicações .NET:

Rodam em https://localhost:5001
Usam HTTPS com certificado de desenvolvimento
Fazem validação rigorosa do Host Header
Podem bloquear requisições externas por política de CORS

Se você simplesmente rodar:

ngrok http 5001

O Ngrok vai tentar criar um túnel HTTP simples.

Resultado? ❌

Você pode receber:

Erro de CORS
400 Bad Request
Erro de Host inválido
Falha de redirecionamento HTTPS

Isso acontece porque:

O .NET espera HTTPS
O Host recebido não será localhost
A requisição chega com domínio externo (.ngrok-free.dev)

3️⃣ A Solução (O Comando Mágico)

O segredo é dizer ao Ngrok duas coisas:

Que o destino já é HTTPS
Que ele deve reescrever o Host Header

Execute:

ngrok http https://localhost:5001 --host-header="localhost:5001"

🔎 O que esse comando faz?

`https://localhost:5001`

Informa ao Ngrok que o backend já está rodando em HTTPS.

`--host-header="localhost:5001"`

Reescreve o cabeçalho da requisição.

Quando a requisição chega na sua API:

O .NET lê o Host como localhost:5001
A validação passa
O roteamento funciona corretamente

💡 Isso evita erros de Host inválido e problemas comuns de CORS relacionados ao domínio inesperado.

4️⃣ Configurando no Front-end

Após rodar o comando, o Ngrok gera uma URL pública:

https://seu-link.ngrok-free.dev

Agora, no seu projeto Front-end, atualize a variável de ambiente:

API_URL=https://seu-link.ngrok-free.dev

Reinicie o projeto e pronto 🚀

Agora você pode:

Desenvolver a interface no seu PC rápido
Consumir a API na máquina corporativa
Acessar o banco via VPN
Trabalhar com performance real

🎁 Bônus: O Ngrok é muito mais que um túnel

Além de resolver o problema de conectividade, o Ngrok oferece recursos poderosos.

🔐 Segurança de Endpoints

Você pode proteger seu túnel com:

OAuth
Restrição de IP
Validação JWT
Basic Authentication

Tudo configurado direto no painel.

📊 Monitoramento de Tráfego

O Ngrok possui um inspetor de tráfego em tempo real.

Você pode visualizar:

Headers
Payload
Status code
Tempo de resposta

Ideal para debugar integrações.

📚 Conclusão

Com o comando correto, é possível expor uma API .NET rodando em HTTPS sem erros de Host ou CORS, mantendo segurança e produtividade.

Essa abordagem permite trabalhar com performance real no Front-end sem abrir mão do acesso ao banco via VPN.

✍️ Stefhany Santos

Software Engineer

Como consertei a câmera de um port de PC usando a API do Windows (Unity IL2CPP Modding)

Stefhany Santos — Sun, 22 Feb 2026 20:10:17 +0000

Fala, comunidade! 👋

Recentemente, me deparei com um problema clássico no mundo dos games: um jogo mobile (Heartopia) ganhou um port para PC, mas trouxe consigo todos os controles de toque. O resultado? Para girar a câmera, o jogador precisava segurar o clique esquerdo e arrastar o mouse. Uma experiência de UX terrível para quem joga no teclado e mouse.

Como desenvolvedora, eu não ia simplesmente aceitar isso. Decidi criar um mod para transformar essa câmera em um "Free Look 360º" contínuo, nativo de jogos de PC. O que parecia simples virou um desafio de engenharia reversa e manipulação de SO.

Bem-vindos ao Heartopia PC Camera Fix, o primeiro projeto open-source do meu estúdio indie, Lovel Studio.

🚧 O Desafio: Unity IL2CPP e o Input Manager

O jogo foi compilado em IL2CPP, o que já dificulta bastante a engenharia reversa se comparado ao Mono tradicional. A arquitetura original utilizava o New Unity Input System altamente acoplado para mobile (ScriptsRefactory.BaseService.Input.InputManager).

Tentar interceptar o UnityEngine.Input diretamente via Harmony Hooks estava quebrando o jogo. A solução? Fazer um bypass na engine e lidar diretamente com o Windows.

🛠️ A Solução: C# + `user32.dll`

Criei um plugin em BepInEx 6 e adotei uma abordagem de "Esteira Virtual" usando a API nativa do Windows.

A arquitetura final do mod (v2.5.0) faz o seguinte:

1. O Paradoxo da Esteira (Virtual Treadmill)
Quando o jogador aperta ALT, eu confino o cursor e simulo um MOUSEEVENTF_RIGHTDOWN. Para permitir o giro infinito (360º), eu leio as coordenadas do monitor via ClientToScreen e teletransporto o cursor (SetCursorPos) de volta para o centro sempre que ele atinge uma margem de 100 pixels. É um loop infinito e invisível de arrasto.

2. Segurança de Interface (WndProc Hook)
O maior bug inicial era: enquanto o jogador girava a câmera livremente, o jogo continuava registrando "cliques" invisíveis na interface, fazendo a personagem atacar do nada.
Para resolver isso, criei um Hook direto no WndProc da janela do jogo:

private IntPtr WndProcHook(IntPtr hWnd, uint msg, IntPtr wParam, IntPtr lParam)
{
    // Bloqueia cliques esquerdos apenas quando a câmera Lovel está ativa
    if (isLocked && (msg == WM_LBUTTONDOWN || msg == WM_LBUTTONUP || msg == WM_LBUTTONDBLCLK))
        return IntPtr.Zero;

    return (oldWndProc != IntPtr.Zero) ? CallWindowProc(oldWndProc, hWnd, msg, wParam, lParam) : IntPtr.Zero;
}

Isso literalmente cega o jogo para cliques físicos esquerdos enquanto o modo de câmera está ativo. Um bloqueio limpo no nível do sistema operacional.

🐛 Aonde preciso da ajuda de vocês (Open Source)

Apesar da estabilidade excelente, há um Known Issue: a câmera sofre um leve stuttering ocasional.
Isso acontece porque a Main Thread da Unity às vezes dá gargalos pesados (ex: carregando chunks ou texturas) e o jogo "perde" o frame exato em que a esteira virtual reseta o mouse para o centro, quebrando o movimento por uma fração de segundo.

O projeto está sob Licença MIT no GitHub. Se você manda bem em C#, engenharia reversa ou otimização de Unity, adoraria receber seus Pull Requests! O objetivo é encontrar os offsets corretos para um Hook nativo na classe controladora de câmera via Harmony, eliminando a dependência da user32.dll.

🔗 Acesse o repositório do Heartopia Camera Fix aqui

Se você joga o game, a aba de Releases já tem o .zip pronto no modelo Drag & Drop pra facilitar a vida.

Adoraria saber a opinião de vocês sobre outras abordagens para injetar inputs em jogos IL2CPP. Como vocês resolveriam esse stuttering da Main Thread?

Desenvolvido com muita quebra de cabeça por Stefhany (Lovel Studio) 💜

Automatizando posts do dev.to no README do GitHub com GitHub Actions

Stefhany Santos — Tue, 17 Feb 2026 13:22:38 +0000

Manter o README do GitHub atualizado com seus conteúdos é uma forma simples (e poderosa) de mostrar consistência, aprendizado contínuo e presença na comunidade dev.

Neste post, vou mostrar como automatizei a exibição dos meus artigos do Dev.to diretamente no README, usando GitHub Actions sem scripts complexos e sem manutenção manual.

🎯 Por que fazer isso?

✅ Seu README fica sempre atualizado
✅ Mostra que você produz conteúdo técnico
✅ Recrutadores veem seus artigos logo de cara
✅ Zero trabalho manual depois da configuração

🧩 A solução

Usei uma GitHub Action pronta chamada blog-post-workflow, que consome feeds RSS (como o do Dev.to) e injeta os posts automaticamente no README.

🛠️ Passo 1 — Criar o workflow
No seu repositório, crie o arquivo:

.github/workflows/blog-posts.yml

Conteúdo:

name: Latest blog post workflow

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  update-readme-with-blog:
    name: Update this repo's README with latest blog posts
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Pull in dev.to posts
        uses: gautamkrishnar/blog-post-workflow@v1
        with:
          feed_list: "https://dev.to/feed/stefhanysantos/"
          max_post_count: 3
          date_format: "dd mmm yyyy"
          template: |
            <div>
              <h4><a href="$url">$title</a> | <em>📅 $date</em></h4>
            </div>

Esse workflow:

Roda diariamente
Pode ser executado manualmente
Atualiza o README automaticamente com os últimos posts

🧷 Passo 2 — Preparar o README

No local onde você quer que os posts apareçam, adicione:

<!-- BLOG-POST-LIST:START -->
<!-- BLOG-POST-LIST:END -->

É exatamente entre esses comentários que a action vai renderizar os artigos.

✨ Resultado final

No README, os posts aparecem assim:

🚀 Título do artigo
📅 10 fev 2026

🚀 Outro artigo técnico
📅 05 fev 2026

Simples, limpo e profissional.

💡 Dica extra

Você pode:

Filtrar por tags
Customizar o template com HTML
Limitar quantidade de posts
Usar isso como portfólio técnico vivo

🚧 Conclusão

Automatizar pequenas coisas como essa faz diferença no longo prazo.
Seu GitHub deixa de ser apenas código e passa a contar a sua história como dev.