Frameworks de modding pour Cyberpunk 2077 : architecture et synergie de CET, REDscript, ArchiveXL et TweakXL

Introduction : L'écosystème de modding de REDengine 4

Contrairement aux moteurs de jeu proposant des boîtes à outils visuelles officielles (à l'instar du Creation Kit de Bethesda) ou reposant sur des environnements de scripts ouverts, le moteur propriétaire REDengine 4 conçu par CD Projekt Red pour Cyberpunk 2077 est une architecture monolithique haute performance écrite en C++. En son sein s'articulent plusieurs sous-systèmes étroitement liés : du bytecode de scripts précompilé, des conteneurs binaires d'archives (.archive) et une base de données relationnelle centrale en mémoire vive nommée TweakDB.

Lors du lancement du jeu, le modding se résumait à des modifications hexadécimales artisanales et au remplacement statique de fichiers dans les conteneurs .archive. Grâce aux efforts de rétro-ingénierie menés par la communauté, un écosystème modulaire de frameworks complémentaires s'est rapidement imposé :

1. Cyber Engine Tweaks (CET) : Interception binaire via proxy de DLL, environnement d'exécution Lua, console superposée ImGui et interrogation directe du RTTI.
2. REDscript : Compilateur de scripts et moteur de patch par méthode pour le langage natif du moteur (proche de Swift).
3. ArchiveXL : Chargeur de ressources dynamique et extension de système de fichiers virtuel (VFS), permettant l'injection additive de modèles 3D sans altération des archives originales.
4. TweakXL : Moteur de modification déclarative en mémoire pour TweakDB, autorisant l'ajout d'objets et de statistiques sans conflit de base de données.
5. Codeware et RED4ext : Socles d'extension C++ gérant le cycle de vie des extensions et l'exposition des types à l'exécution.

Maîtriser le fonctionnement conjoint de ces quatre outils est indispensable pour diagnostiquer les plantages au démarrage (flatliners), résoudre les échecs de compilation de scripts et préserver la stabilité de son installation au fil des mises à jour du jeu.

Vue d'ensemble de l'architecture : Topologie d'intégration des frameworks

Le schéma ci-dessous détaille les points d'ancrage de chaque framework au sein de REDengine 4 lors du lancement et de la boucle principale du jeu :

+-------------------------------------------------------------------------+
|                  Cyberpunk2077.exe (Cœur REDengine 4)                  |
+-------------------------------------------------------------------------+
       |                                                 |
       v (Proxying de DLL : version.dll)                 v (Hooks de démarrage)
+-----------------------------------+           +-------------------------+
|    Cyber Engine Tweaks (CET)      |           |      RED4ext Core       |
| - Hooks C++ natifs                |           | - Chargeur de DLL       |
| - Moteur Lua 5.1/LuaJIT           |           | - Cycle de vie & RTTI   |
| - Console et overlay ImGui        |           +-------------------------+
| - Appels directs de fonctions RTTI|                 |              |
+-----------------------------------+                 v              v
                                             +-------------+  +-----------+
                                             |  ArchiveXL  |  |  TweakXL  |
                                             | (VFS virtuel)|  | (TweakDB) |
                                             +-------------+  +-----------+
                                                    |               |
+-----------------------------------+               |               |
|            REDscript              |               |               |
| - Compile r6/scripts en bytecode  | <-------------+---------------+
| - Hooks (@replace, @wrap)         | (Fournit liaisons & enregistrements)
| - Modifie les classes du jeu      |
+-----------------------------------+

Chaque framework cible une couche technique bien définie :

• CET agit depuis l'extérieur par proxying de bibliothèque dynamique, exécutant des scripts Lua asynchrones et dessinant des interfaces graphiques.
• RED4ext s'initialise au plus profond du moteur et offre une plateforme d'accueil aux modules C++ d'ArchiveXL et TweakXL.
• REDscript s'exécute avant la boucle de jeu principale pour analyser et recompiler les scripts dans le cache de bytecode du moteur.
• ArchiveXL et TweakXL étendent dynamiquement en mémoire le chargement des ressources et la base de données sans réécrire les fichiers d'origine.

1. Cyber Engine Tweaks (CET) : Injection binaire et environnement Lua

Vecteur d'exécution : Proxying de bibliothèque de liens dynamiques (DLL)

CET s'injecte dans le processus Cyberpunk2077.exe en exploitant l'ordre de recherche des DLL sous Windows. Le système d'exploitation cherche d'abord dans le répertoire de l'exécutable (bin\x64\) avant de scruter les répertoires système. CET fournit un fichier version.dll personnalisé. Au lancement du jeu, Windows charge cette DLL en mémoire ; CET initialise ses hooks internes et relaie de façon transparente les appels de l'API Windows vers la vraie DLL située dans C:\Windows\System32\.

RTTI (Run-Time Type Information) et réflexion du moteur

L'atout majeur de CET réside dans sa capacité à explorer le système RTTI interne de REDengine 4. Le moteur recense l'ensemble de ses classes C++, structures, énumérations et fonctions dans des tables de métadonnées :

• CET parcourt ces tables lors de l'initialisation du jeu.
• Il expose directement ces fonctions et variables C++ au moteur Lua intégré (LuaJIT).
• Les moddeurs écrivent leurs scripts dans bin\x64\plugins\cyber_engine_tweaks\mods\[NomDuMod]\init.lua.
• Les scripts peuvent écouter les événements du jeu (onInit, onUpdate, onDraw), récupérer l'entité du joueur via Game.GetPlayer() et déclencher des commandes moteur en temps réel.

Intégration de Dear ImGui et console de débogage

CET intègre la bibliothèque graphique légère Dear ImGui directement sur la chaîne de permutation (swapchain) de DirectX 12. Dès que la touche de raccourci est pressée, CET intercepte les entrées du clavier et de la souris pour ouvrir une console interactive permettant d'inspecter les variables et de paramétrer les mods.

2. REDscript : Compilateur de scripts natifs et modification ciblée

Contrairement à CET qui fait tourner des scripts Lua externes, REDscript modifie directement le code de jeu natif de REDengine.

La chaîne de compilation de REDscript

La quasi-totalité de la logique de jeu de Cyberpunk 2077 (quêtes, interface utilisateur, inventaire, arbre de compétences, IA des PNJ) est codée dans un langage propriétaire semblable à Swift. À la livraison du jeu, ces scripts sont compilés sous forme de bytecode binaire dans r6\cache\final.redscripts.

REDscript redéfinit ce cycle :

1. Au lancement du jeu, REDscript analyse l'ensemble des fichiers .reds du dossier r6\scripts\.
2. Il génère un arbre syntaxique abstrait (AST).
3. Il décompile les définitions de base stockées dans le cache du jeu.
4. Il fusionne les modifications apportées par les mods dans l'arbre d'origine et recompile l'ensemble en un cache unifié (r6\cache\moddedOnly.redscripts).
5. La machine virtuelle de REDengine exécute ce nouveau bytecode avec des performances natives.

Annotations de méthodes : Prévention des conflits de scripts

À l'origine, modifier une seule ligne de code imposait d'écraser des fichiers de script complets de plusieurs milliers de lignes, créant des incompatibilités directes entre mods. REDscript résout ce problème grâce à un système d'annotations ciblées :

• @replaceMethod(NomClasse) : Remplace entièrement la méthode ciblée.
• @wrapMethod(NomClasse) : Encapsule la méthode existante, permettant d'exécuter du code avant et après wrappedMethod() tout en conservant la logique d'origine.
• @addMethod(NomClasse) : Injecte une méthode inédite dans une classe existante.
• @addField(NomClasse) : Ajoute de nouvelles variables d'état à une classe du moteur.

// Exemple de hook non destructif avec REDscript sur la gestion des dégâts
@wrapMethod(PlayerPuppet)
protected cb func OnTakeDamage(damageEvent: ref[gameDamageReceivedEvent]) -> Bool {
    // Code personnalisé avant exécution
    ModLog("Dégâts interceptés : " + ToString(damageEvent.totalDamageReceived));
    
    // Appel du comportement natif du jeu
    let result: Bool = wrappedMethod(damageEvent);
    
    // Code personnalisé après exécution
    return result;
}

3. ArchiveXL : Système de fichiers virtuel et ajout dynamique de modèles

Avant l'avènement d'ArchiveXL, intégrer une nouvelle tenue ou une arme exigeait de remplacer les modèles 3D (maillages) et les textures d'objets préexistants dans les archives .archive. Deux mods remplaçant la même veste étaient donc strictement incompatibles.

Chargement additif des ressources

ArchiveXL fonctionne comme une extension de RED4ext et intercepte le gestionnaire de ressources du moteur (CResourceLoader) :

• Il permet l'ajout direct de nouveaux fichiers sans écraser les archives officielles.
• Les nouveaux maillages 3D, textures et squelettes d'animation sont rassemblés dans des conteneurs .archive placés dans archive\pc\mod\.
• Un fichier descripteur YAML portant l'extension .xl y est adjoint (par exemple : archive\pc\mod\MonArmure.xl).

Injection de fabriques et morphing dynamique

À partir du fichier .xl, ArchiveXL prend en charge :

• L'enregistrement dynamique des nouvelles entités dans les fabriques du moteur (resource.factories).
• L'adaptation morphologique automatique (Morphing), garantissant que les tenues s'ajustent parfaitement aux différentes corpulences du joueur sans déformation visuelle (clipping).
• L'injection de chaînes de localisation dynamiques, permettant aux nouveaux objets d'afficher un nom et une description traduits dans toutes les langues sans modifier les fichiers de texte officiels.

4. TweakXL : Modification en mémoire vive de TweakDB via YAML

Dans REDengine 4, TweakDB est la base de données relationnelle qui définit les statistiques d'armes, les indices de protection des armures, les compétences, les formules d'artisanat et les caractéristiques des PNJ.

Les limites des bases binaires statiques

À l'état brut, TweakDB est compilée dans le fichier binaire r6\cache\tweakdb.bin. Les premiers outils de la communauté tentaient de régénérer ce fichier dans sa totalité, ce qui entraînait l'écrasement pur et simple des données des mods installés précédemment par le dernier fichier enregistré.

Injection déclarative en mémoire via YAML

TweakXL résout ce problème en intervenant directement au chargement en mémoire :

1. Le moteur charge le fichier tweakdb.bin officiel en mémoire vive.
2. TweakXL intercepte le pointeur de la base lors de sa phase d'initialisation.
3. Il analyse tous les fichiers de configuration .yaml et .tweak présents dans r6\tweaks\.
4. Il duplique des enregistrements existants, modifie des attributs précis ou ajoute de nouveaux identifiants uniques directement en mémoire :

  # Déclaration TweakXL enregistrant un nouveau katana personnalisé
Items.MyCustomKatana:
  $type: gamedataItem_Record
  $base: Items.Preset_Katana_Default
  displayName: LocKey#MyCustomKatana_Name
  visualTags: [ "MyCustomKatana_Mesh" ]
  quality: Quality.Legendary
  statModifiers:
    - !append Items.BaseDamageModifier

Ce mode opératoire permet à des centaines de mods d'équipements de fonctionner simultanément sans le moindre conflit de fichiers sur le disque.

Matrice de diagnostic et résolution des pannes

En cas de plantage ou de dysfonctionnement après installation de mods, consultez la grille suivante pour localiser le composant défaillant :

Script PowerShell de diagnostic automatisé

Exécutez ce script PowerShell pour vous assurer de la présence des fichiers indispensables et vérifier l'absence d'erreurs dans les journaux de compilation :

  # Script de vérification de l'environnement de modding de Cyberpunk 2077
  param(
      [string]$GameRoot = "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077"
  )
  
  Write-Host "=== Diagnostic des Frameworks Cyberpunk 2077 ===" -ForegroundColor Cyan
  
  # 1. Vérification des fichiers binaires fondamentaux
  $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"
      "Compilateur 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 détecté (Version : $version)" -ForegroundColor Green
      } else {
          Write-Host "[ABSENT] $name introuvable dans : $path" -ForegroundColor Red
      }
  }
  
  # 2. Analyse du journal récent de compilation REDscript
  $redscriptLog = "$GameRoot\r6\logs\redscript_rCURRENT.log"
  if (Test-Path $redscriptLog) {
      Write-Host "`nAnalyse du journal de REDscript en cours..." -ForegroundColor Cyan
      $errors = Select-String -Path $redscriptLog -Pattern "ERROR", "FATAL" | Select-Object -First 5
      if ($errors) {
          Write-Host "[ATTENTION] Erreurs relevées dans la compilation de REDscript :" -ForegroundColor Yellow
          $errors | ForEach-Object { Write-Host "  " $_.Line -ForegroundColor Red }
      } else {
          Write-Host "[OK] Aucune erreur détectée dans le dernier journal de compilation." -ForegroundColor Green
      }
  }

Bonnes pratiques pour une configuration pérenne

1. Respect strict des correspondances de versions : Chaque patch de CD Projekt Red redéfinit les adresses mémoire du jeu. Il est recommandé de bloquer les mises à jour automatiques du jeu jusqu'à ce que de nouvelles versions de CET, RED4ext, ArchiveXL et TweakXL soient publiées.
2. Préservation du dossier Content d'origine : Proscrivez les mods obsolètes nécessitant de remplacer des fichiers dans archive\pc\content\. Les mods modernes s'installent exclusivement dans archive\pc\mod\, r6\ ou red4ext\.
3. Analyse des journaux avant toute réinstallation : En cas d'anomalie, inspectez systématiquement r6\logs\redscript_rCURRENT.log et le dossier red4ext\logs\. L'analyse de l'intégrité des fichiers sous Steam ou GOG écrase les fichiers de configuration sans résoudre l'incompatibilité de fond.
4. Appui sur une démarche d'ingénierie logicielle : Maîtriser les principes de l'injection dynamique, des systèmes de fichiers virtuels et de la mutation de données en mémoire permet de stabiliser des centaines de modifications actives. Des répertoires techniques de référence comme 365Finds fournissent les clés architecturales pour comprendre les moteurs de jeu et garantir une expérience fluide et durable.

Références

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