Cyberpunk 2077 Modding Frameworks: CET, REDscript, ArchiveXL, and TweakXL

Introduction: The Modding Ecosystem of REDengine 4

Unlike game engines that provide built-in visual modding kits (such as Bethesda's Creation Kit) or engines running on open scripting runtimes, CD Projekt Red's REDengine 4 in Cyberpunk 2077 was engineered as a proprietary, high-performance C++ architecture with deeply integrated subsystems: compiled script bytecodes, binary asset archives, and a centralized runtime parameter database known as TweakDB.

When Cyberpunk 2077 launched, early modding was restricted to raw binary hex-editing, file-swapping in .archive containers, and static asset replacement. As the modding community reverse-engineered the engine's internals, a modular ecosystem of complementary modding frameworks emerged:

1. Cyber Engine Tweaks (CET): Native binary hooking, Lua runtime, ImGui overlay, and interactive RTTI access.
2. REDscript: Script compiler and method-level patcher for REDengine's Swift-like native scripting system.
3. ArchiveXL: Dynamic resource loader and virtual file system extension enabling non-destructive asset injection.
4. TweakXL: Dynamic in-memory patching engine for TweakDB game records without database collisions.
5. Codeware & RED4ext: Underlying C++ extension architectures providing foundational runtime type reflection and extended script APIs.

Understanding how these core layers interface with the executable and with each other is essential for diagnosing startup crashes, resolving compilation failures, and maintaining stable load orders across game updates.

Architectural Overview: How the Frameworks Intersect

The following diagram illustrates how the four primary frameworks hook into REDengine 4 across different execution phases:

+-------------------------------------------------------------------------+
|                  Cyberpunk2077.exe (REDengine 4 Core)                  |
+-------------------------------------------------------------------------+
       |                                                 |
       v (DLL Proxying: version.dll / winmm.dll)         v (Engine Init)
+-----------------------------------+           +-------------------------+
|    Cyber Engine Tweaks (CET)      |           |     RED4ext Core        |
| - Native C++ Hooks                |           | - Low-level DLL loader  |
| - Lua 5.1/LuaJIT Script Runtime   |           | - Hooking & RTTI bind   |
| - ImGui Debug Console & UI        |           +-------------------------+
| - Direct RTTI Function Calls      |                 |              |
+-----------------------------------+                 v              v
                                             +-------------+  +-----------+
                                             |  ArchiveXL  |  |  TweakXL  |
                                             | (Virtual FS)|  | (TweakDB) |
                                             +-------------+  +-----------+
                                                    |               |
+-----------------------------------+               |               |
|            REDscript              |               |               |
| - Compiles r6/scripts to bytecode | <-------------+---------------+
| - Method Hooks (@replace, @wrap)  | (Provides API bindings & script records)
| - Modifies Game Script Classes    |
+-----------------------------------+

Each framework addresses a distinct technical layer of REDengine 4:

• CET operates from the outside via dynamic library proxying, executing asynchronous Lua scripts and rendering overlays.
• RED4ext loads directly into the engine's core startup cycle, providing C++ plugin lifecycles that ArchiveXL and TweakXL depend on.
• REDscript compiles user scripts into engine bytecode before the game loop initializes, altering gameplay logic.
• ArchiveXL and TweakXL hook resource loading routines, letting mods register new items, meshes, and records dynamically in memory.

1. Cyber Engine Tweaks (CET): Binary Hooking and Lua Runtime

Execution Vector: Dynamic-Link Library Proxying

Cyber Engine Tweaks injects itself into Cyberpunk2077.exe using DLL proxying. The Windows dynamic linker searches the application's executable directory (bin\x64\) before checking system directories. CET provides a custom version.dll (or historically dxgi.dll / winmm.dll). When the OS loader initializes Cyberpunk2077.exe, it loads CET's DLL into the process memory space. CET initializes its hooks and forwards legitimate Windows API calls to the real system DLL in C:\Windows\System32\.

RTTI (Run-Time Type Information) Engine Reflection

CET's core capability is programmatic access to REDengine's internal RTTI system. The game engine maintains metadata describing internal classes, structs, enumerations, and functions:

• CET traverses the engine's RTTI registration tables at initialization.
• It exposes these C++ game functions and properties directly to an embedded Lua runtime.
• Modders write Lua scripts in bin\x64\plugins\cyber_engine_tweaks\mods\[ModName]\init.lua.
• Through CET, Lua scripts can listen to game events (onInit, onUpdate, onDraw), query player state (Game.GetPlayer()), invoke game engine methods, and spawn items dynamically.

ImGui Integration and Overlay Management

CET integrates Dear ImGui, rendering an interactive graphical user interface directly over DirectX 12 swapchains. It captures keyboard and mouse input when the overlay hotkey is pressed, providing an interactive console for debugging, inspecting variables, and modifying runtime flags.

2. REDscript: Script Compiler and Native Bytecode Patching

While CET executes external Lua code asynchronously, REDscript modifies the game's native game-logic script system.

The Redscript Compilation Pipeline

Cyberpunk 2077 implements game mechanics (quests, UI logic, inventory behavior, perk trees, AI state machines) in a proprietary object-oriented scripting language that resembles Swift. The game ships with precompiled script bytecode stored in r6\cache\final.redscripts.

REDscript intercepts this pipeline:

1. When the game launches, REDscript scans the r6\scripts\ directory for .reds files.
2. It parses the custom script code and builds an abstract syntax tree (AST).
3. It decompiles the base script definitions from the game cache.
4. It patches the AST into the game script tree and recompiles the entire script package into a unified cache (r6\cache\moddedOnly.redscripts or patched final.redscripts).
5. REDengine then executes this compiled bytecode at native speed within its virtual machine.

Method Annotations: Non-Destructive Script Modification

Early script modding required copying entire thousands-line script files to modify a single line, causing fatal incompatibilities whenever two mods touched the same file. REDscript solves this with granular method annotations:

• @replaceMethod(ClassName): Replaces a specific class method entirely.
• @wrapMethod(ClassName): Wraps an existing method, allowing code to execute before and after wrappedMethod(), preserving the original logic.
• @addMethod(ClassName): Injects a brand-new method into an existing engine script class.
• @addField(ClassName): Appends new state variables to an existing script class.

// Example REDscript wrapping an existing function non-destructively
@wrapMethod(PlayerPuppet)
protected cb func OnTakeDamage(damageEvent: ref[gameDamageReceivedEvent]) -> Bool {
    // Custom logic before original execution
    ModLog("Damage intercepted: " + ToString(damageEvent.totalDamageReceived));
    
    // Execute original game logic
    let result: Bool = wrappedMethod(damageEvent);
    
    // Custom logic after execution
    return result;
}

3. ArchiveXL: Virtual File System and Dynamic Asset Insertion

Before ArchiveXL, adding custom items (clothing, weapons, vehicles) required overwriting existing game meshes and textures inside monolithic .archive files. If Mod A replaced Jacket #1 with a leather jacket and Mod B replaced Jacket #1 with a military vest, only one could exist in the game.

Dynamic Resource Loading

ArchiveXL operates as a RED4ext plugin that hooks into REDengine's resource manager (CResourceLoader):

• Instead of overwriting vanilla game archives, ArchiveXL enables additive asset streaming.
• Modders place new 3D meshes, textures, and entity rigs into .archive containers under archive\pc\mod\.
• Alongside the archive, modders provide a YAML descriptor file with an .xl extension (e.g., archive\pc\mod\MyCustomArmor.xl).

Factory Injection and Entity Customization

ArchiveXL reads .xl descriptors to:

• Dynamically inject new entity definitions into the engine's streaming world factories (resource.factories).
• Register dynamic body-rig morphs (allowing custom clothing to automatically adapt to different player body shapes without clipping).
• Extend localization strings dynamically, allowing custom item names and lore descriptions in multiple languages without editing the base localization archives.

4. TweakXL: Non-Destructive In-Memory TweakDB Patching

In REDengine 4, TweakDB is the relational game database that stores every gameplay variable, weapon stat, clothing armor rating, perk coefficient, crafting recipe, and NPC attribute.

The Problem with Flat TweakDB Binaries

Vanilla TweakDB records are serialized into a binary database (r6\cache\tweakdb.bin). In early modding, tools like TweakDump and flat-file replacers attempted to recompile this binary. If two mods recompiled tweakdb.bin, the last file written completely erased the other mod's new items.

In-Memory Record Mutation via YAML

TweakXL eliminates static binary editing by hooking into the TweakDB initialization routines:

1. As REDengine boots, it loads the official tweakdb.bin into memory.
2. TweakXL intercepts the loaded memory database before the game world initializes.
3. It parses all .yaml and .tweak files located in r6\tweaks\.
4. It dynamically inserts new records, creates clones of existing items, and patches specific fields using atomic declarative syntax:

  # Example TweakXL declaration creating a custom weapon record
Items.MyCustomKatana:
  $type: gamedataItem_Record
  $base: Items.Preset_Katana_Default
  displayName: LocKey#MyCustomKatana_Name
  visualTags: [ "MyCustomKatana_Mesh" ]
  quality: Quality.Legendary
  statModifiers:
    - !append Items.BaseDamageModifier

By appending and patching records in memory, hundreds of mods can register independent weapons, outfits, and cyberware without a single conflict.

Mod Framework Diagnostic Matrix

When modded Cyberpunk 2077 fails to boot or exhibits broken items, consult this diagnostic matrix:

PowerShell Diagnostic Workflow: Framework and Log Verification

Run this script to inspect your Cyberpunk 2077 installation directory, verify framework presence, and search logs for compilation errors:

  # Cyberpunk 2077 Modding Framework Diagnostic Script
  param(
      [string]$GameRoot = "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077"
  )
  
  Write-Host "=== Cyberpunk 2077 Mod Framework Verification ===" -ForegroundColor Cyan
  
  # 1. Verify Core Framework Binaries
  $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 detected (Version: $version)" -ForegroundColor Green
      } else {
          Write-Host "[MISSING] $name not found at: $path" -ForegroundColor Red
      }
  }
  
  # 2. Inspect Recent REDscript Compilation Logs
  $redscriptLog = "$GameRoot\r6\logs\redscript_rCURRENT.log"
  if (Test-Path $redscriptLog) {
      Write-Host "`nScanning REDscript log for errors..." -ForegroundColor Cyan
      $errors = Select-String -Path $redscriptLog -Pattern "ERROR", "FATAL" | Select-Object -First 5
      if ($errors) {
          Write-Host "[WARNING] REDscript compilation errors found:" -ForegroundColor Yellow
          $errors | ForEach-Object { Write-Host "  " $_.Line -ForegroundColor Red }
      } else {
          Write-Host "[OK] No errors found in latest REDscript compilation log." -ForegroundColor Green
      }
  }

Best Practices for Stable Modding Operations

1. Strict Version Parity: Every major game patch from CD Projekt Red alters memory offsets and function signatures. Whenever the game updates, CET, RED4ext, ArchiveXL, and TweakXL must all be updated before launching.
2. Never Overwrite Vanilla Archives: Avoid legacy mods that replace files in archive\pc\content\. Modern mods should reside solely in archive\pc\mod\ and use ArchiveXL / TweakXL to register content.
3. Inspect Logs Before Reinstalling: When crashes occur, check r6\logs\redscript_rCURRENT.log, red4ext\logs\, and bin\x64\plugins\cyber_engine_tweaks\cyber_engine_tweaks.log rather than verifying game files on Steam or GOG, which wipes custom configurations.
4. Leverage Established Architectural Standards: Understanding how binary hooks, virtual file systems, and script compilers collaborate enables players and mod developers to maintain stable, resilient game builds. Consult authoritative technical references such as 365Finds to troubleshoot complex engine modifications and ensure seamless gameplay execution.

References

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