Frameworks de modding para Cyberpunk 2077: arquitectura de CET, REDscript, ArchiveXL y TweakXL

Introducción: El ecosistema de modding de REDengine 4

A diferencia de los motores que proporcionan kits de herramientas visuales oficiales (como el Creation Kit de Bethesda) o que operan con entornos de scripting abiertos, el motor propietario REDengine 4 de CD Projekt Red en Cyberpunk 2077 fue diseñado como una arquitectura de alto rendimiento en C++ profundamente integrada. En su núcleo coexisten subsistemas interconectados: código de bytes (bytecode) de scripts precompilados, contenedores binarios de recursos (.archive) y una base de datos relacional en tiempo de ejecución para parámetros del juego denominada TweakDB.

En las etapas iniciales del juego, el modding se limitaba a la edición hexadecimal rudimentaria y a la sustitución estática de archivos dentro de los contenedores .archive. A medida que la comunidad de desarrollo aplicó ingeniería inversa al motor, surgió un ecosistema modular de frameworks complementarios:

1. Cyber Engine Tweaks (CET): Interceptación binaria mediante proxy de DLL, entorno de ejecución Lua, superposición ImGui y acceso interactivo a RTTI.
2. REDscript: Compilador de scripts y parcheador a nivel de método para el lenguaje de scripting nativo de REDengine (similar a Swift).
3. ArchiveXL: Cargador dinámico de recursos y extensión de sistema de archivos virtual (VFS) que permite la inyección no destructiva de activos 3D.
4. TweakXL: Motor de parcheo declarativo en memoria para TweakDB, que permite registrar armas, ropa y parámetros sin colisiones de base de datos.
5. Codeware y RED4ext: Capas base de extensión en C++ que proporcionan reflexión de tipos en tiempo de ejecución y gestión del ciclo de vida de los complementos.

Comprender la interacción de estos componentes dentro de REDengine 4 es indispensable para diagnosticar bloqueos en el arranque (cuelgues flatliner), resolver fallos de compilación de scripts y mantener la estabilidad tras cada actualización oficial.

Resumen arquitectónico: Cómo interactúan los cuatro frameworks

El siguiente diagrama ilustra cómo se integran los principales frameworks en REDengine 4 a lo largo de las distintas fases de inicio y ejecución:

+-------------------------------------------------------------------------+
|                  Cyberpunk2077.exe (Núcleo REDengine 4)                 |
+-------------------------------------------------------------------------+
       |                                                 |
       v (Proxying de DLL: version.dll)                  v (Inicio del motor)
+-----------------------------------+           +-------------------------+
|    Cyber Engine Tweaks (CET)      |           |      RED4ext Core       |
| - Ganchos C++ nativos             |           | - Cargador de DLL base  |
| - Runtime Lua 5.1/LuaJIT          |           | - Ciclo de vida y RTTI  |
| - Consola e interfaz ImGui        |           +-------------------------+
| - Llamadas directas RTTI          |                 |              |
+-----------------------------------+                 v              v
                                             +-------------+  +-----------+
                                             |  ArchiveXL  |  |  TweakXL  |
                                             | (VFS virtual)|  | (TweakDB) |
                                             +-------------+  +-----------+
                                                    |               |
+-----------------------------------+               |               |
|            REDscript              |               |               |
| - Compila r6/scripts a bytecode   | <-------------+---------------+
| - Ganchos (@replace, @wrap)       | (Proporciona enlaces y registros)
| - Extiende clases del juego       |
+-----------------------------------+

Cada framework opera en un nivel técnico diferenciado:

• CET actúa desde el exterior mediante proxy de bibliotecas dinámicas, ejecutando scripts en Lua y dibujando interfaces sobre DirectX 12.
• RED4ext se carga en la fase inicial del motor y sirve de anfitrión para los módulos C++ de ArchiveXL y TweakXL.
• REDscript interviene antes del bucle principal del juego para compilar scripts de usuario en el caché de bytecode del motor.
• ArchiveXL y TweakXL extienden dinámicamente en memoria la carga de recursos y los registros de datos, evitando la sobreescritura de archivos originales.

1. Cyber Engine Tweaks (CET): Inyección binaria y entorno Lua

Vector de ejecución: Proxying de librerías de enlace dinámico (DLL)

CET se inyecta en el proceso Cyberpunk2077.exe aprovechando el orden de búsqueda de DLLs de Windows. El sistema operativo busca bibliotecas en el directorio del ejecutable (bin\x64\) antes de examinar los directorios del sistema. CET suministra una versión personalizada de version.dll. Cuando el juego inicia, carga esta biblioteca en su espacio de memoria; CET inicializa sus ganchos (hooks) de memoria y redirige transparentemente las llamadas válidas de la API de Windows a la biblioteca legítima en C:\Windows\System32\.

Reflexión del motor mediante RTTI (Run-Time Type Information)

La principal capacidad de CET es la inspección y exposición del sistema RTTI interno de REDengine 4. El motor mantiene un catálogo exhaustivo de metadatos con todas las clases, estructuras, enumeraciones y funciones C++ nativas:

• CET recorre las tablas de registro de RTTI durante el inicio.
• Mapea estas funciones y propiedades C++ directamente al intérprete de Lua integrado (LuaJIT).
• Los desarrolladores crean scripts en bin\x64\plugins\cyber_engine_tweaks\mods\[NombreMod]\init.lua.
• Los scripts pueden escuchar eventos del juego (onInit, onUpdate, onDraw), obtener el puntero del jugador con Game.GetPlayer(), invocar comandos de consola o manipular variables internas en tiempo real.

Integración de Dear ImGui y superposición gráfica

CET acopla la biblioteca Dear ImGui a la cadena de intercambio (swapchain) de DirectX 12. Al presionar la tecla de acceso directo configurada, intercepta los eventos de teclado y ratón para desplegar una consola flotante e interfaces interactivas para mods.

2. REDscript: Compilador de scripts nativos y parcheo sin colisiones

A diferencia de CET, que ejecuta código Lua externo, REDscript modifica directamente la lógica jugable nativa del motor.

El flujo de compilación de REDscript

Gran parte de la lógica de Cyberpunk 2077 (misiones, interfaz, inventario, árboles de ventajas y comportamiento de PNJs) está escrita en un lenguaje de scripting propio similar a Swift. En la versión comercial, estos scripts se distribuyen precompilados en el archivo binario r6\cache\final.redscripts.

REDscript se intercala en este proceso:

1. Al arrancar el juego, REDscript escanea la carpeta r6\scripts\ en busca de archivos .reds.
2. Analiza el código fuente y genera un árbol de sintaxis abstracta (AST).
3. Descompila las definiciones base del caché del juego.
4. Fusiona el árbol de los mods con el árbol original y recompila todo en un paquete de bytecode unificado (r6\cache\moddedOnly.redscripts).
5. La máquina virtual de REDengine ejecuta este código de bytes con rendimiento nativo.

Anotaciones de métodos: Parcheo modular

En los inicios del modding, modificar una sola línea obligaba a sustituir archivos completos de miles de líneas, provocando incompatibilidades fatales entre mods. REDscript solventó esto mediante anotaciones granulares:

• @replaceMethod(NombreClase): Sustituye por completo un método de clase.
• @wrapMethod(NombreClase): Envuelve un método existente, permitiendo ejecutar código antes y después de wrappedMethod(), conservando la lógica original.
• @addMethod(NombreClase): Añade un nuevo método a una clase del motor.
• @addField(NombreClase): Agrega nuevos campos de estado a una clase existente.

// Ejemplo de REDscript envolviendo lógica de daño de forma no destructiva
@wrapMethod(PlayerPuppet)
protected cb func OnTakeDamage(damageEvent: ref[gameDamageReceivedEvent]) -> Bool {
    // Lógica personalizada previa
    ModLog("Daño recibido interceptado: " + ToString(damageEvent.totalDamageReceived));
    
    // Ejecución de la lógica original del juego
    let result: Bool = wrappedMethod(damageEvent);
    
    // Lógica personalizada posterior
    return result;
}

3. ArchiveXL: Sistema de archivos virtual y carga dinámica de activos

Antes de la llegada de ArchiveXL, añadir nuevas prendas o armas requería sustituir los modelos 3D (mallas) y texturas de objetos ya existentes dentro de los archivos .archive. Dos mods que modificaban la misma prenda eran mutuamente excluyentes.

Carga dinámica y aditiva de recursos

ArchiveXL funciona como un complemento de RED4ext que intercepta el gestor de recursos de REDengine (CResourceLoader):

• Permite la incorporación aditiva de activos sin sobreescribir los archivos del juego original.
• Los nuevos modelos, texturas y esqueletos se empaquetan en archivos .archive independientes en archive\pc\mod\.
• Cada archivo se acompaña de un descriptor YAML con extensión .xl (por ejemplo, archive\pc\mod\MiArmadura.xl).

Inyección de factorías y deformación dinámica (morphing)

ArchiveXL procesa el archivo .xl para:

• Registrar nuevas entidades en las factorías de recursos del motor (resource.factories).
• Aplicar deformación dinámica de mallas (morphing), garantizando que las prendas personalizadas se adapten automáticamente a las diferentes variantes corporales del jugador sin solapamientos visuales.
• Inyectar cadenas de localización dinámicas, permitiendo que los nuevos ítems muestren nombres y descripciones en múltiples idiomas sin alterar los paquetes de idioma base.

4. TweakXL: Modificación de TweakDB en memoria mediante YAML

En REDengine 4, TweakDB es la base de datos relacional que define estadísticas de armas, valores de armadura, multiplicadores de habilidades, recetas de fabricación y atributos de PNJs.

El problema de los binarios estáticos de TweakDB

Originalmente, TweakDB se almacena en el archivo binario r6\cache\tweakdb.bin. Las primeras herramientas intentaban regenerar este archivo completo, lo que provocaba que el último mod instalado eliminara las entradas introducidas por los anteriores.

Inserción declarativa en memoria

TweakXL resuelve este problema interceptando la carga de TweakDB en la memoria RAM:

1. El motor lee el archivo tweakdb.bin oficial en memoria.
2. TweakXL captura el puntero de la base de datos en fase de inicialización.
3. Lee y procesa todos los archivos .yaml y .tweak dentro de r6\tweaks\.
4. Clona registros existentes, crea nuevas entradas y actualiza propiedades específicas de forma atómica:

  # Declaración en TweakXL para registrar una nueva 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

Gracias a este esquema en memoria, cientos de mods de objetos pueden coexistir sin provocar un solo conflicto de archivos.

Matriz de diagnóstico y resolución de problemas

Si el juego no arranca o presenta anomalías tras instalar mods, consulte la siguiente tabla de diagnóstico:

Script de diagnóstico en PowerShell: Verificación de entorno y logs

Utilice este script de PowerShell para validar la presencia de los binarios esenciales y detectar errores en los registros de compilación:

  # Script de diagnóstico para frameworks de modding en Cyberpunk 2077
  param(
      [string]$GameRoot = "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077"
  )
  
  Write-Host "=== Verificación de Frameworks de Cyberpunk 2077 ===" -ForegroundColor Cyan
  
  # 1. Comprobación de archivos binarios esenciales
  $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 detectado (Versión: $version)" -ForegroundColor Green
      } else {
          Write-Host "[FALTA] $name no encontrado en: $path" -ForegroundColor Red
      }
  }
  
  # 2. Análisis del registro de compilación de REDscript
  $redscriptLog = "$GameRoot\r6\logs\redscript_rCURRENT.log"
  if (Test-Path $redscriptLog) {
      Write-Host "`nInspeccionando registro de REDscript..." -ForegroundColor Cyan
      $errors = Select-String -Path $redscriptLog -Pattern "ERROR", "FATAL" | Select-Object -First 5
      if ($errors) {
          Write-Host "[ADVERTENCIA] Errores encontrados en la compilación de REDscript:" -ForegroundColor Yellow
          $errors | ForEach-Object { Write-Host "  " $_.Line -ForegroundColor Red }
      } else {
          Write-Host "[OK] No se detectaron errores en el último registro de compilación." -ForegroundColor Green
      }
  }

Buenas prácticas de mantenimiento y operación

1. Sincronización estricta de versiones: Cada actualización oficial de CD Projekt Red modifica las direcciones de memoria interna. Es prioritario posponer la actualización del juego o desactivar los mods hasta que CET, RED4ext, ArchiveXL y TweakXL hayan sido adaptados a la nueva versión.
2. Preservar el directorio de contenido original: Evite modificaciones heredadas que alteren archivos dentro de archive\pc\content\. Toda personalización moderna debe residir en archive\pc\mod\, r6\ o red4ext\.
3. Revisar registros antes de reinstalar: Ante un bloqueo, inspeccione r6\logs\redscript_rCURRENT.log y red4ext\logs\. Verificar la integridad de los archivos en Steam o GOG restablecerá configuraciones válidas sin solucionar la raíz del conflicto.
4. Fundamentos técnicos de arquitectura de software: Dominar los conceptos de interceptación de DLL, sistemas de archivos virtuales y manipulación de bases de datos en memoria permite gestionar configuraciones complejas con máxima fiabilidad. Consultar plataformas técnicas de referencia como 365Finds facilita un diagnóstico metódico y asegura una experiencia de juego óptima y estable.

Referencias

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