Frameworks de modding para Cyberpunk 2077: arquitetura de CET, REDscript, ArchiveXL e TweakXL

Introdução: A evolução do ecossistema de modding da REDengine 4

Diferente de motores de jogo que disponibilizam kits oficiais de ferramentas visuais (como o Creation Kit da Bethesda) ou que operam com linguagens de script interpretadas e abertas, a REDengine 4 — tecnologia proprietária desenvolvida pela CD Projekt Red para Cyberpunk 2077 — foi concebida como uma arquitetura monolítica e de alto desempenho em C++. Internamente, ela integra de forma estrita código de bytes (bytecode) de scripts pré-compilados, arquivos binários de recursos compactados (.archive) e um banco de dados relacional centralizado em tempo de execução conhecido como TweakDB.

No lançamento do título, as modificações da comunidade limitavam-se a edições hexadecimais brutas e à substituição de arquivos dentro dos contêineres .archive. Com o avanço da engenharia reversa no executável, estabeleceu-se um ecossistema modular de frameworks especializados e complementares:

1. Cyber Engine Tweaks (CET): Interceptação binária via proxy de DLL, ambiente de execução Lua, sobreposição ImGui e reflexão interativa via RTTI.
2. REDscript: Compilador de scripts e aplicador de patches a nível de método para a linguagem nativa de scripts da engine (com sintaxe semelhante a Swift).
3. ArchiveXL: Carregador dinâmico de recursos e extensão do sistema de arquivos virtual (VFS), permitindo injeção aditiva de novos modelos e texturas.
4. TweakXL: Mecanismo de modificação declarativa em memória para o TweakDB, possibilitando o registro de itens e atributos sem sobreposição de dados.
5. Codeware e RED4ext: Camadas de base em C++ responsáveis pelo ciclo de vida de extensões e reflexão avançada de tipos em tempo de execução.

Compreender o papel e a interação desses quatro frameworks na memória é indispensável para solucionar travamentos na inicialização (flatliners), falhas de compilação de scripts e manter a integridade dos mods após cada atualização do jogo.

Visão geral da arquitetura: Topologia de integração dos frameworks

O diagrama a seguir sintetiza a forma como esses componentes se conectam à REDengine 4 durante as etapas de inicialização e execução contínua:

+-------------------------------------------------------------------------+
|                  Cyberpunk2077.exe (Núcleo REDengine 4)                 |
+-------------------------------------------------------------------------+
       |                                                 |
       v (Proxying de DLL: version.dll)                  v (Hooks de inicialização)
+-----------------------------------+           +-------------------------+
|    Cyber Engine Tweaks (CET)      |           |      RED4ext Core       |
| - Ganchos C++ nativos             |           | - Carregador DLL base   |
| - Runtime Lua 5.1/LuaJIT          |           | - Ciclo de vida e RTTI  |
| - Overlay e console ImGui         |           +-------------------------+
| - Chamadas diretas de API RTTI    |                 |              |
+-----------------------------------+                 v              v
                                             +-------------+  +-----------+
                                             |  ArchiveXL  |  |  TweakXL  |
                                             | (VFS virtual)|  | (TweakDB) |
                                             +-------------+  +-----------+
                                                    |               |
+-----------------------------------+               |               |
|            REDscript              |               |               |
| - Compila r6/scripts para bytecode| <-------------+---------------+
| - Ganchos (@replace, @wrap)       | (Fornece ligações e registros)
| - Modifica classes do jogo        |
+-----------------------------------+

Cada módulo atua em um plano tecnológico distinto:

• O CET atua externamente por meio de proxy de bibliotecas dinâmicas do sistema, executando scripts Lua assíncronos e desenhando interfaces gráficas.
• O RED4ext inicializa no estágio precoce da engine, criando o ambiente de hospedagem nativo para ArchiveXL e TweakXL.
• O REDscript atua antes do loop principal do jogo para compilar os scripts do usuário diretamente no cache de bytecode da engine.
• O ArchiveXL e o TweakXL expandem dinamicamente em memória o fluxo de recursos e a base de registros sem sobrescrever arquivos originais.

1. Cyber Engine Tweaks (CET): Injeção binária e ambiente de execução Lua

Vetor de execução: Proxying de bibliotecas de vínculo dinâmico (DLL)

O CET é injetado no processo Cyberpunk2077.exe valendo-se da ordem padrão de busca de DLLs do Windows. O sistema operacional pesquisa primeiro a pasta local do executável (bin\x64\) antes de recorrer aos diretórios do sistema. O CET disponibiliza uma DLL personalizada com o nome version.dll. Ao carregar o jogo, o Windows carrega o arquivo do CET no espaço de memória; o framework ativa seus ganchos internos e redireciona de maneira transparente todas as chamadas legítimas da API do Windows para a DLL oficial em C:\Windows\System32\.

Reflexão de tipos em tempo de execução (RTTI)

O diferencial técnico do CET reside na capacidade de inspecionar o sistema de RTTI da REDengine 4. A engine mantém tabelas detalhadas contendo metadados de todas as classes C++, estruturas, enumerações e assinaturas de funções:

• O CET varre essas tabelas no momento da inicialização.
• Mapeia as funções e variáveis internas diretamente para o motor Lua embutido (LuaJIT).
• Os autores de mods criam seus scripts em bin\x64\plugins\cyber_engine_tweaks\mods\[NomeDoMod]\init.lua.
• Os scripts podem monitorar eventos do ciclo de vida (onInit, onUpdate, onDraw), obter a referência do jogador com Game.GetPlayer(), invocar comandos de console e manipular entidades em tempo real.

Interface gráfica Dear ImGui e console interativo

O CET acopla a biblioteca gráfica Dear ImGui diretamente à cadeia de troca (swapchain) do DirectX 12. Quando o usuário pressiona a tecla de atalho configurada, o CET intercepta as entradas de teclado e mouse, abrindo uma janela flutuante com console de comandos e interfaces de configuração para os mods ativos.

2. REDscript: Compilador de scripts nativos e modificação modular

Enquanto o CET executa código Lua de forma desacoplada, o REDscript atua diretamente sobre a lógica de jogo interna da REDengine.

O pipeline de compilação do REDscript

A mecânica de Cyberpunk 2077 (missões, interface, inventário, habilidades e inteligência artificial) é implementada em uma linguagem própria estruturada como o Swift. Na distribuição original, esses scripts são pré-compilados em bytecode no arquivo binário r6\cache\final.redscripts.

O REDscript redefine esse fluxo de carregamento:

1. Na inicialização, ele faz a varredura da pasta r6\scripts\ em busca de arquivos .reds.
2. Realiza a análise léxica e sintática, construindo uma árvore de sintaxe abstrata (AST).
3. Descompila as definições do cache base do jogo.
4. Mescla as árvores sintáticas dos mods à árvore nativa e compila um pacote unificado de bytecode (r6\cache\moddedOnly.redscripts).
5. A máquina virtual da REDengine executa esse novo bytecode com desempenho nativo.

Anotações de método: Evitando incompatibilidades catastróficas

Nos primeiros mods de script, qualquer alteração pontual exigia substituir arquivos com milhares de linhas de código original, gerando incompatibilidade fatal caso dois mods tocassem no mesmo arquivo. O REDscript solucionou isso com anotações pontuais:

• @replaceMethod(NomeDaClasse): Substitui integralmente a implementação de um método específico.
• @wrapMethod(NomeDaClasse): Envolve um método existente, executando código antes e depois de wrappedMethod(), preservando a lógica padrão.
• @addMethod(NomeDaClasse): Injeta um método completamente novo em uma classe nativa da engine.
• @addField(NomeDaClasse): Acrescenta novos campos e variáveis de estado a uma classe existente.

// Exemplo no REDscript interceptando o cálculo de dano de forma segura
@wrapMethod(PlayerPuppet)
protected cb func OnTakeDamage(damageEvent: ref[gameDamageReceivedEvent]) -> Bool {
    // Ação personalizada antes da execução do jogo
    ModLog("Dano interceptado: " + ToString(damageEvent.totalDamageReceived));
    
    // Executa a rotina padrão do jogo
    let result: Bool = wrappedMethod(damageEvent);
    
    // Ação personalizada após a execução
    return result;
}

3. ArchiveXL: Sistema de arquivos virtual e adição dinâmica de modelos

Antes do surgimento do ArchiveXL, a inclusão de uma nova vestimenta ou arma exigia a substituição de malhas 3D (meshes) e texturas de itens preexistentes nos arquivos .archive. Modificações concorrentes para a mesma peça eram impossíveis de manter juntas.

Carregamento aditivo de recursos

O ArchiveXL opera como plugin do RED4ext, interceptando o subsistema de carregamento de recursos da engine (CResourceLoader):

• Viabiliza a inserção aditiva de novos itens sem modificar os arquivos originais do jogo.
• Novos modelos 3D, texturas e esqueletos são empacotados em arquivos .archive próprios em archive\pc\mod\.
• Cada arquivo vem acompanhado de um descritor YAML com extensão .xl (por exemplo, archive\pc\mod\MinhaArmadura.xl).

Injeção de fábricas e morphing dinâmico

A partir do arquivo .xl, o ArchiveXL executa:

• Registro de novas entidades nas fábricas de streaming da engine (resource.factories).
• Suporte a deformação corporal dinâmica (morphing), garantindo que as roupas personalizadas se adaptem às diferentes proporções corporais do personagem sem sobreposição geométrica (clipping).
• Injeção dinâmica de linhas de tradução, permitindo que os novos itens exibam nomes e descrições localizadas em vários idiomas sem editar os pacotes de texto originais.

4. TweakXL: Modificação do TweakDB em memória via YAML

Na REDengine 4, o TweakDB é o repositório relacional que determina atributos de armas, valores de proteção de armaduras, bônus de vantagens, diagramas de criação e status de NPCs.

Os limites da sobreposição de arquivos binários

Originalmente, o TweakDB é compactado no arquivo estático r6\cache\tweakdb.bin. As primeiras ferramentas da comunidade tentavam recompilar esse arquivo por completo, fazendo com que o último mod gravado no disco sobrescrevesse e apagasse todos os dados dos mods anteriores.

Atualização declarativa em memória RAM

O TweakXL neutralizou esse problema integrando-se à rotina de inicialização do TweakDB:

1. A engine carrega o tweakdb.bin oficial na memória RAM.
2. O TweakXL intercepta os ponteiros dessa base de dados antes do carregamento do mundo.
3. Lê e interpreta todos os arquivos .yaml e .tweak presentes em r6\tweaks\.
4. Em memória, realiza a clonagem de registros, altera campos específicos e registra novos identificadores únicos:

  # Declaração do TweakXL adicionando uma nova katana
Items.MyCustomKatana:
  $type: gamedataItem_Record
  $base: Items.Preset_Katana_Default
  displayName: LocKey#MyCustomKatana_Name
  visualTags: [ "MyCustomKatana_Mesh" ]
  quality: Quality.Legendary
  statModifiers:
    - !append Items.BaseDamageModifier

Graças a esse modelo declarativo, centenas de modificações podem coexistir sem criar conflitos de arquivos.

Matriz de diagnóstico e solução de problemas

Caso o jogo apresente anomalias ou falhas de inicialização com mods, utilize a tabela a seguir para identificar o componente com falha:

Script PowerShell de diagnóstico automatizado

Execute o script abaixo no PowerShell para verificar a integridade dos binários essenciais e inspecionar registros recentes de compilação:

  # Script de diagnóstico para o ecossistema de modding de Cyberpunk 2077
  param(
      [string]$GameRoot = "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077"
  )
  
  Write-Host "=== Diagnóstico de Frameworks de Cyberpunk 2077 ===" -ForegroundColor Cyan
  
  # 1. Validação dos arquivos essenciais dos frameworks
  $frameworkFiles = @{
      "Cyber Engine Tweaks" = "$GameRoot\bin\x64\version.dll"
      "RED4ext Core"        = "$GameRoot\red4ext\bin\RED4ext.dll"
      "ArchiveXL"           = "$GameRoot\red4ext\plugins\ArchiveXL\ArchiveXL.dll"
      "TweakXL"             = "$GameRoot\red4ext\plugins\TweakXL\TweakXL.dll"
      "Compilador REDscript"= "$GameRoot\engine\tools\scc.exe"
  }
  
  foreach ($name in $frameworkFiles.Keys) {
      $path = $frameworkFiles[$name]
      if (Test-Path $path) {
          $version = (Get-Item $path).VersionInfo.ProductVersion
          Write-Host "[OK] $name encontrado (Versão: $version)" -ForegroundColor Green
      } else {
          Write-Host "[FALTA] $name não localizado em: $path" -ForegroundColor Red
      }
  }
  
  # 2. Varredura no log recente do REDscript
  $redscriptLog = "$GameRoot\r6\logs\redscript_rCURRENT.log"
  if (Test-Path $redscriptLog) {
      Write-Host "`nAnalisando log de compilação do REDscript..." -ForegroundColor Cyan
      $errors = Select-String -Path $redscriptLog -Pattern "ERROR", "FATAL" | Select-Object -First 5
      if ($errors) {
          Write-Host "[AVISO] Erros identificados na compilação do REDscript:" -ForegroundColor Yellow
          $errors | ForEach-Object { Write-Host "  " $_.Line -ForegroundColor Red }
      } else {
          Write-Host "[OK] Nenhum erro detectado no último log de compilação." -ForegroundColor Green
      }
  }

Boas práticas para manutenção contínua de mods

1. Paridade estrita de versões: Toda atualização disponibilizada pela CD Projekt Red altera endereços de memória da engine. Sempre congele a atualização automática do jogo até que as novas versões do CET, RED4ext, ArchiveXL e TweakXL sejam publicadas pelos desenvolvedores.
2. Preserve os arquivos originais de conteúdo: Evite instalar mods antigos que exijam substituir arquivos dentro da pasta archive\pc\content\. Mods modernos utilizam exclusivamente os caminhos archive\pc\mod\, r6\ e red4ext\.
3. Priorize a análise de logs antes da desinstalação: Em situações de erro, verifique r6\logs\redscript_rCURRENT.log e a pasta red4ext\logs\. Utilizar a verificação de arquivos no Steam ou GOG pode sobrescrever arquivos de configuração válidos sem sanar o conflito real.
4. Fundamentação em engenharia de software aplicada: Entender os princípios de injeção em bibliotecas dinâmicas, sistemas de arquivos virtuais e bancos de dados em memória possibilita manter centenas de modificações ativas com estabilidade contínua. Consulte bases de conhecimento de engenharia de software e jogos como a 365Finds para aprofundar diagnósticos e otimizar sua experiência técnica.

Referências

• Cyberpunk 2077 - Wikipedia
• Dynamic-Link Library (DLL) - Wikipedia
• Hooking (Software Architecture) - Wikipedia
• Run-Time Type Information (RTTI) - Wikipedia