Cyberpunk 2077 Modding-Frameworks: Architektur und Zusammenspiel von CET, REDscript, ArchiveXL und TweakXL

Einführung: Das Modding-Ökosystem der REDengine 4

Im Gegensatz zu Spiele-Engines mit integrierten visuellen Editoren (wie dem Creation Kit von Bethesda) oder offenen Scripting-Laufzeitumgebungen basiert die von CD Projekt Red entwickelte REDengine 4 in Cyberpunk 2077 auf einer hochgradig integrierten, geschlossenen C++-Architektur. Das System verknüpft vorkompilierten Script-Bytecode, binäre Archiv-Container (.archive) und eine zentrale relationale Parameter-Datenbank zur Laufzeit, die sogenannte TweakDB.

In der Anfangsphase des Spiels beschränkte sich das Modding weitgehend auf manuelle Hex-Manipulationen und den statischen Austausch von Dateien innerhalb der .archive-Archive. Durch systematische Reverse-Engineering-Arbeiten der Modding-Community entstand im Laufe der Zeit ein modulares Gefüge aus aufeinander abgestimmten Laufzeit-Frameworks:

1. Cyber Engine Tweaks (CET): Native C++-Hooks via DLL-Proxying, integrierte Lua-Laufzeitumgebung, ImGui-Overlay und Zugriff auf die Engine-RTTI.
2. REDscript: Bytecode-Compiler und Methoden-Patcher für die Swift-ähnliche Skriptsprache der REDengine.
3. ArchiveXL: Dynamischer Ressourcen-Lader und Erweiterung des virtuellen Dateisystems (VFS) zur nicht-destruktiven Einspeisung neuer 3D-Modelle und Texturen.
4. TweakXL: Deklarativer In-Memory-Patcher für die TweakDB, der das Hinzufügen von Ausrüstungs- und Attributsdaten ohne Dateikonflikte ermöglicht.
5. Codeware und RED4ext: Grundlegende C++-Erweiterungsschichten zur Verwaltung von Plugin-Lebenszyklen und Laufzeit-Typinformationen.

Ein fundiertes Verständnis der Zusammensetzung und Funktionsweise dieser vier Komponenten ist unerlässlich, um Spielabstürze beim Start (Flatliner), Skript-Kompilierungsfehler und Inkompatibilitäten nach offiziellen Spiel-Patches gezielt zu analysieren und zu beheben.

Architekturübersicht: Das Zusammenspiel der vier Frameworks

Das folgende Diagramm zeigt, an welchen Schnittstellen der REDengine 4 die Kernkomponenten während des Bootvorgangs und der Laufzeit ansetzen:

+-------------------------------------------------------------------------+
|                  Cyberpunk2077.exe (REDengine 4 Kern)                  |
+-------------------------------------------------------------------------+
       |                                                 |
       v (DLL-Proxying: version.dll)                     v (Engine-Start-Hooks)
+-----------------------------------+           +-------------------------+
|    Cyber Engine Tweaks (CET)      |           |      RED4ext Core       |
| - Native C++-Hooks                |           | - Low-Level-DLL-Loader  |
| - Lua 5.1/LuaJIT-Laufzeitumgebung |           | - Lebenszyklus & RTTI   |
| - ImGui-Konsole & Debug-Overlay   |           +-------------------------+
| - Direkte RTTI-Funktionsaufrufe   |                 |              |
+-----------------------------------+                 v              v
                                             +-------------+  +-----------+
                                             |  ArchiveXL  |  |  TweakXL  |
                                             | (Virtuelles |  | (TweakDB) |
                                             |  Dateisystem|  |           |
                                             +-------------+  +-----------+
                                                    |               |
+-----------------------------------+               |               |
|            REDscript              |               |               |
| - Kompiliert r6/scripts zu Bytecode <-------------+---------------+
| - Methoden-Hooks (@replace, @wrap)| (Liefert Bindings & Datensätze)
| - Modifiziert Engine-Klassen      |
+-----------------------------------+

Jedes Framework erfüllt eine spezialisierte Aufgabe innerhalb der Engine:

• CET operiert über DLL-Proxying von außen, führt asynchrone Lua-Skripte aus und rendert Overlays über DirectX 12.
• RED4ext klinkt sich tief in die Initialisierungsphase ein und dient als Host-Umgebung für C++-Erweiterungen wie ArchiveXL und TweakXL.
• REDscript greift vor der Hauptspielschleife ein, um Skripte aus dem Dateisystem zu parsen und direkt in den Bytecode-Cache der Engine zu kompilieren.
• ArchiveXL und TweakXL erweitern die Ressourcenverwaltung und die Datenbank zur Laufzeit im RAM, ohne Originaldateien auf dem Datenträger zu verändern.

1. Cyber Engine Tweaks (CET): DLL-Proxying und Lua-Laufzeitumgebung

Funktionsweise des DLL-Proxying

CET nutzt die Standard-Suchreihenfolge von Windows für dynamische Bibliotheken aus. Windows durchsucht das Anwendungsverzeichnis (bin\x64\) vor den Systemverzeichnissen nach benötigten DLLs. CET platziert eine maßgeschneiderte version.dll in diesem Ordner. Wenn Cyberpunk2077.exe gestartet wird, lädt das Betriebssystem diese DLL in den Prozessspeicher. CET initialisiert seine internen Speicher-Hooks und leitet reguläre Windows-API-Aufrufe transparent an die echte Systemdatei in C:\Windows\System32\ weiter.

RTTI (Run-Time Type Information) Engine-Reflektion

Das Kernmerkmal von CET ist der Zugriff auf das interne RTTI-System der REDengine 4. Die Engine führt detaillierte Metadatentabellen mit allen C++-Klassen, Strukturen, Enums und Methoden:

• CET durchsucht diese Register beim Start und erfasst Funktionszeiger und Klassendefinitionen.
• Diese Schnittstellen werden direkt an die integrierte LuaJIT-Umgebung übergeben.
• Modder schreiben ihre Skripte in bin\x64\plugins\cyber_engine_tweaks\mods\[ModName]\init.lua.
• Über Lua können Entwickler Lebenszyklus-Ereignisse abfangen (onInit, onUpdate, onDraw), mit Game.GetPlayer() den Spielerstatus abfragen und Engine-Funktionen für komplexe Gameplay-Modifikationen ausführen.

ImGui-Integration und Overlay-Steuerung

CET integriert die Benutzeroberflächenbibliothek Dear ImGui direkt in die Swapchain von DirectX 12. Durch Drücken der konfigurierten Overlay-Taste fängt CET Maus- und Tastatureingaben ab und öffnet eine interaktive Konsole zur Variableninspektion und Steuerung von Mod-Parametern.

2. REDscript: Nativer Skript-Compiler und modulare Methoden-Hooks

Im Gegensatz zu CET, das Skripte extern in Lua abarbeitet, greift REDscript direkt in die native Gameplay-Logik der REDengine ein.

Die REDscript-Kompilierungspipeline

Die Spiellogik von Cyberpunk 2077 (Quests, Benutzeroberfläche, Inventarverwaltung, Talentbäume und KI-Zustände) ist in einer proprietären, Swift-ähnlichen Skriptsprache verfasst. Bei der Veröffentlichung liefert CDPR diese Skripte als kompilierten Bytecode in r6\cache\final.redscripts aus.

REDscript schaltet sich in diesen Prozess ein:

1. Beim Spielstart scannt REDscript den Ordner r6\scripts\ nach .reds-Dateien.
2. Es analysiert die Syntax und baut einen abstrakten Syntaxbaum (AST) auf.
3. Es dekompiliert die Basisskripte aus dem Spiel-Cache.
4. Es fusioniert die Mod-Skripte mit den Engine-Klassen und erzeugt ein einheitliches Bytecode-Paket (r6\cache\moddedOnly.redscripts).
5. Die virtuelle Maschine der REDengine führt diesen modifizierten Bytecode mit nativer Geschwindigkeit aus.

Methoden-Annotationen zur Konfliktvermeidung

Frühe Skript-Mods erforderten das vollständige Ersetzen tausende Zeilen langer Skriptdateien, was unweigerlich zu Inkompatibilitäten führte, sobald zwei Mods denselben Bereich berührten. REDscript löst dies durch präzise Annotationen:

• @replaceMethod(KlassenName): Ersetzt eine spezifische Methode vollständig.
• @wrapMethod(KlassenName): Schachtelt eine vorhandene Methode ein, wodurch benutzerdefinierter Code vor und nach wrappedMethod() ausgeführt werden kann.
• @addMethod(KlassenName): Fügt einer bestehenden Engine-Klasse eine neue Methode hinzu.
• @addField(KlassenName): Erweitert eine Klasse um neue Zustandsvariablen.

// Beispiel für einen nicht-destruktiven Hook in REDscript
@wrapMethod(PlayerPuppet)
protected cb func OnTakeDamage(damageEvent: ref[gameDamageReceivedEvent]) -> Bool {
    // Eigener Code vor der Originalausführung
    ModLog("Schaden abgefangen: " + ToString(damageEvent.totalDamageReceived));
    
    // Ausführung der nativen Spiellogik
    let result: Bool = wrappedMethod(damageEvent);
    
    // Eigener Code nach der Originalausführung
    return result;
}

3. ArchiveXL: Virtuelles Dateisystem und dynamisches Asset-Streaming

Vor der Entwicklung von ArchiveXL erforderte das Hinzufügen neuer Kleidungsstücke oder Waffen das Überschreiben bestehender 3D-Modelle (Meshes) und Texturen in den offiziellen Archiven. Zwei Mods für denselben Gegenstand schlossen sich gegenseitig aus.

Additives Laden von Ressourcen

ArchiveXL fungiert als RED4ext-Plugin und klinkt sich in den Ressourcen-Manager der REDengine (CResourceLoader) ein:

• Es ermöglicht das additive Einspeisen von Assets, ohne bestehende .archive-Dateien zu modifizieren.
• Neue 3D-Modelle, Texturen und Rigs werden in eigenständigen .archive-Dateien unter archive\pc\mod\ abgelegt.
• Parallel dazu wird eine YAML-Deskriptordatei mit der Endung .xl hinterlegt (z. B. archive\pc\mod\MeineRuestung.xl).

Factory-Injection und dynamisches Morphing

Anhand der .xl-Datei übernimmt ArchiveXL:

• Die dynamische Registrierung neuer Entity-Definitionen in den weltweiten Streaming-Fabriken (resource.factories).
• Die Unterstützung dynamischer Mesh-Deformationen (Morphing), sodass Kleidungsstücke sich automatisch an unterschiedliche Körpertypen anpassen, ohne dass es zu Darstellungsfehlern (Clipping) kommt.
• Die Injektion dynamischer Lokalisierungstexte, wodurch neue Gegenstände mehrsprachige Namen und Beschreibungen erhalten, ohne dass Sprachdateien entpackt werden müssen.

4. TweakXL: Deklaratives In-Memory-Patching der TweakDB

In der REDengine 4 ist die TweakDB die relationale Datenbank, in der alle numerischen Werte und Eigenschaften hinterlegt sind – darunter Waffenschaden, Rüstungswerte, Talentkoeffizienten und Handwerksrezepte.

Die Schwachstelle statischer Binärdateien

Ursprünglich ist die TweakDB in der Datei r6\cache\tweakdb.bin serialisiert. Frühe Modding-Werkzeuge versuchten, diese Binärdatei komplett neu zu generieren, wodurch die jeweils zuletzt gespeicherte Datei alle Einträge vorheriger Mods unwiederbringlich überschrieb.

In-Memory-Modifikation über YAML

TweakXL verhindert dies durch direktes Eingreifen in den Ladevorgang im Arbeitsspeicher:

1. Die Engine liest die offizielle tweakdb.bin in den RAM.
2. TweakXL fängt den Initialisierungszeiger der Datenbank ab.
3. Es liest alle .yaml- und .tweak-Dateien im Verzeichnis r6\tweaks\ ein.
4. Im Arbeitsspeicher werden bestehende Datensätze geklont, Werte modifiziert und neue Einträge registriert:

  # TweakXL-Deklaration zur Registrierung eines neuen Katana-Datensatzes
Items.MyCustomKatana:
  $type: gamedataItem_Record
  $base: Items.Preset_Katana_Default
  displayName: LocKey#MyCustomKatana_Name
  visualTags: [ "MyCustomKatana_Mesh" ]
  quality: Quality.Legendary
  statModifiers:
    - !append Items.BaseDamageModifier

Dank dieser Methode können Hunderte von Ausrüstungs-Mods parallel betrieben werden, ohne dass Konflikte auf Dateiebene entstehen.

Diagnose- und Problemlösungsmatrix

Bei Startproblemen oder Fehlern im Spielverlauf hilft folgende Übersicht bei der Eingrenzung der Ursache:

PowerShell-Diagnoseskript: Dateiintegrität und Protokollprüfung

Mit dem folgenden PowerShell-Skript lassen sich die Kernkomponenten auf Vorhandensein prüfen und die letzten Kompilierungsprotokolle auf Fehler untersuchen:

  # Diagnose-Skript für Cyberpunk 2077 Modding-Frameworks
  param(
      [string]$GameRoot = "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077"
  )
  
  Write-Host "=== Cyberpunk 2077 Mod-Framework-Diagnose ===" -ForegroundColor Cyan
  
  # 1. Überprüfung der wesentlichen Binärdateien
  $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"
      "REDscript-Compiler"  = "$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 gefunden (Version: $version)" -ForegroundColor Green
      } else {
          Write-Host "[FEHLT] $name nicht gefunden unter: $path" -ForegroundColor Red
      }
  }
  
  # 2. Analyse der aktuellen REDscript-Kompilierungsprotokolle
  $redscriptLog = "$GameRoot\r6\logs\redscript_rCURRENT.log"
  if (Test-Path $redscriptLog) {
      Write-Host "`nPrüfe REDscript-Kompilierungsprotokoll..." -ForegroundColor Cyan
      $errors = Select-String -Path $redscriptLog -Pattern "ERROR", "FATAL" | Select-Object -First 5
      if ($errors) {
          Write-Host "[WARNUNG] Fehler im REDscript-Protokoll gefunden:" -ForegroundColor Yellow
          $errors | ForEach-Object { Write-Host "  " $_.Line -ForegroundColor Red }
      } else {
          Write-Host "[OK] Keine Fehler im letzten REDscript-Protokoll." -ForegroundColor Green
      }
  }

Best Practices für einen stabilen Mod-Betrieb

1. Versionsparität sicherstellen: Jedes Update von CD Projekt Red verändert interne Speicheradressen. Nach einem Patch sollten automatische Spiele-Updates pausiert werden, bis kompatible Versionen von CET, RED4ext, ArchiveXL und TweakXL vorliegen.
2. Standard-Inhaltsverzeichnisse unberührt lassen: Vermeiden Sie veraltete Mods, die Dateien in archive\pc\content\ ersetzen. Moderne Modifikationen gehören ausschließlich in die Ordner archive\pc\mod\, r6\ oder red4ext\.
3. Protokolldateien vor Neuinstallationen prüfen: Bei Fehlern sollten immer zuerst r6\logs\redscript_rCURRENT.log und red4ext\logs\ konsultiert werden. Das automatische Überprüfen der Spieldateien über Steam oder GOG überschreibt häufig Konfigurationsdateien, ohne das zugrundeliegende Mod-Problem zu lösen.
4. Verständnis der Systemarchitektur: Wer die Prinzipien von DLL-Injection, virtuellen Dateisystemen und In-Memory-Patching versteht, kann auch umfangreiche Mod-Sammlungen dauerhaft stabil betreiben. Technische Nachschlagewerke wie 365Finds vermitteln fundiertes Wissen über Engine-Strukturen, um Fehlerursachen methodisch zu analysieren und ein reibungsloses Spielerlebnis zu gewährleisten.

Referenzen

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