사이버펑크 2077 모딩 프레임워크 분석: CET, REDscript, ArchiveXL 및 TweakXL 연동 구조

서론: REDengine 4 모딩 생태계의 진화와 구조

베데스다의 Creation Kit과 같은 공식 시각화 툴셋을 제공하거나 개방형 스크립트 런타임을 채택한 여타 게임 엔진과 달리, CD 프로젝트 레드가 《사이버펑크 2077》(Cyberpunk 2077)에 적용한 독자 엔진 REDengine 4는 고성능 C++ 기반의 폐쇄형 아키텍처입니다. 그 내부에는 컴파일된 스크립트 바이트코드, 바이너리 리소스 아카이브(.archive), 그리고 게임 내 모든 파라미터가 등록된 런타임 중앙 데이터베이스인 TweakDB가 상호 긴밀하게 결합되어 있습니다.

초기 모딩은 16진수 헥스 에디팅이나 기존 .archive 컨테이너 내부의 정적 자산을 직접 덮어쓰는 단순 치환 방식에 머물렀습니다. 그러나 엔진에 대한 역공학이 진행됨에 따라, 기능별로 고도화된 모듈형 런타임 프레임워크 생태계가 정립되었습니다:

1. Cyber Engine Tweaks (CET): DLL 프록시 기반의 네이티브 C++ 후킹, Lua 스크립트 런타임 및 ImGui 디버그 콘솔.
2. REDscript: Swift 유사 독자 스크립트 언어를 컴파일하고 메서드 단위로 무손실 패치하는 바이트코드 인젝터.
3. ArchiveXL: 원본 파일을 보존한 채 신규 3D 메시, 텍스처, 엔티티를 동적 스트리밍하는 가상 파일 시스템 확장기.
4. TweakXL: TweakDB를 메모리상에서 선언적으로 수정하여 모드 간 충돌 없이 신규 장비 및 수치를 등록하는 패치 엔진.
5. Codeware 및 RED4ext: 런타임 타입 리플렉션과 C++ 플러그인 라이프사이클을 제공하는 핵심 기반 인프라.

이들 프레임워크가 REDengine 4 내부에서 동작하는 상호작용 원리를 이해하는 것은 시작 직후 강제 종료(Flatliner) 현상, 스크립트 컴파일 오류, 대규모 모드 로드 순서 충돌을 진단하고 해결하는 데 필수적입니다.

아키텍처 개요: 4대 핵심 프레임워크의 상호작용 구조

다음 다이어그램은 REDengine 4의 부팅 및 실행 단계에서 각 프레임워크가 연결되는 기술적 위치를 보여줍니다:

+-------------------------------------------------------------------------+
|                  Cyberpunk2077.exe (REDengine 4 코어 프로세스)           |
+-------------------------------------------------------------------------+
       |                                                 |
       v (DLL 프록시 로딩: version.dll)                  v (엔진 초기화 훅)
+-----------------------------------+           +-------------------------+
|    Cyber Engine Tweaks (CET)      |           |      RED4ext 코어       |
| - 네이티브 C++ 메모리 후킹        |           | - 로우레벨 DLL 로더     |
| - Lua 5.1/LuaJIT 스크립트 런타임  |           | - 수명주기 관리 & RTTI  |
| - ImGui 디버그 콘솔 & UI          |           +-------------------------+
| - RTTI 엔진 함수/속성 직접 호출   |                 |              |
+-----------------------------------+                 v              v
                                             +-------------+  +-----------+
                                             |  ArchiveXL  |  |  TweakXL  |
                                             | (가상 파일계)|  | (TweakDB) |
                                             +-------------+  +-----------+
                                                    |               |
+-----------------------------------+               |               |
|            REDscript              |               |               |
| - r6/scripts 소스를 바이트코드로  | <-------------+---------------+
| - 메서드 후킹 (@replace, @wrap)   | (스크리프트용 데이터 바인딩 제공)
| - 게임 코어 스크립트 클래스 확장  |
+-----------------------------------+

각 프레임워크는 REDengine 4의 서로 다른 계층을 담당합니다:

• CET는 외부에서 DLL 프록시 기법으로 시스템 호출을 가로채 비동기 Lua 스크립트를 구동하고 UI 오버레이를 렌더링합니다.
• RED4ext는 엔진 초기화 심층부에서 실행되어 ArchiveXL 및 TweakXL의 C++ 플러그인 호스트 환경을 조성합니다.
• REDscript는 메인 게임 루프 진입 전 사용자 스크립트를 컴파일하여 엔진 고유의 바이트코드 캐시에 주입합니다.
• ArchiveXL과 TweakXL은 메모리상에서 자원 스트리밍과 데이터베이스 레코드를 비파괴 방식으로 동적 등록합니다.

1. Cyber Engine Tweaks (CET): 바이너리 후킹과 Lua 런타임

진입 벡터: 동적 링크 라이브러리 프록싱 (DLL Proxying)

CET는 Windows 운영체제의 DLL 검색 우선순위를 활용하여 프로세스에 침투합니다. Windows는 실행 파일이 위치한 디렉터리(bin\x64\)의 라이브러리를 시스템 폴더보다 먼저 검색합니다. CET는 자체 제작한 version.dll을 배치하여 Cyberpunk2077.exe 구동 시 가장 먼저 메모리에 로드됩니다. CET는 내부 후킹을 초기화한 후 정규 Windows API 호출을 C:\Windows\System32\version.dll로 투명하게 릴레이합니다.

런타임 타입 정보 (RTTI) 엔진 리플렉션

CET의 핵심 기술력은 REDengine 4의 내부 RTTI 시스템을 전수 순회하는 능력에 있습니다. 게임 엔진은 내부의 모든 C++ 클래스, 구조체, 열거형, 멤버 함수 메타데이터를 테이블로 보관합니다:

• CET는 초기화 단계에서 RTTI 등록 테이블을 검색하여 함수 포인터를 확보합니다.
• 이를 내장된 LuaJIT 가상 머신에 브리지 형태로 바인딩합니다.
• 모더는 bin\x64\plugins\cyber_engine_tweaks\mods\[모드이름]\init.lua에 스크립트를 작성합니다.
• Lua 코드는 게임 이벤트(onInit, onUpdate, onDraw)를 구독하고, Game.GetPlayer()로 플레이어 엔티티를 제어하거나 엔진 고유 함수를 호출하여 콘솔 치트 및 복잡한 편의 기능을 구현합니다.

ImGui 기반 인터랙티브 콘솔

CET는 경량 UI 라이브러리 Dear ImGui를 DirectX 12 스왑체인에 바인딩합니다. 지정된 오버레이 단축키를 입력하면 키보드와 마우스 입력을 가로채 플로팅 콘솔을 표시하며, 런타임 변수 수정, 콘솔 명령어 실행 및 모드 설정 패널을 직관적으로 조작할 수 있습니다.

2. REDscript: 네이티브 스크립트 컴파일러와 무손실 패치

외부에서 비동기 Lua를 실행하는 CET와 달리, REDscript는 게임 본체의 코어 게임플레이 로직을 직접 수정하고 확장합니다.

REDscript 컴파일 파이프라인

《사이버펑크 2077》의 퀘스트 로직, UI 인터페이스, 인벤토리 시스템, 퍽(특전) 트리, NPC AI는 Swift와 유사한 CDPR 자체 스크립트 언어로 작성되어 있으며, 최종 바이너리에는 r6\cache\final.redscripts 파일에 바이트코드로 컴파일되어 포함됩니다.

REDscript는 이 프로세스를 가로챕니다:

1. 게임 실행 시, REDscript는 r6\scripts\ 폴더 내 모든 .reds 파일을 검색합니다.
2. 구문 분석을 거쳐 추상 구문 트리(AST)를 구성합니다.
3. 게임 캐시에서 원본 클래스 및 함수 시그니처를 역컴파일합니다.
4. 모드 스크립트 트리를 게임 스크립트 트리에 병합한 후, 통합된 바이트코드 캐시(r6\cache\moddedOnly.redscripts)로 재컴파일합니다.
5. REDengine 가상 머신이 패치된 바이트코드를 네이티브 속도로 실행합니다.

메서드 어노테이션을 통한 모드 충돌 방지

초기 스크립트 모드는 단 몇 줄을 고치기 위해 수천 줄 분량의 원본 파일을 통째로 덮어써야 했으므로 동일 파일을 건드리는 모드끼리 충돌이 불가피했습니다. REDscript는 정밀한 어노테이션 시스템으로 이를 극복했습니다:

• @replaceMethod(클래스명): 특정 클래스 메서드를 완전히 대체.
• @wrapMethod(클래스명): 기존 메서드를 감싸서 wrappedMethod() 호출 전후에 커스텀 코드를 삽입(기존 로직 보존).
• @addMethod(클래스명): 기존 엔진 스크립트 클래스에 신규 메서드를 동적 주입.
• @addField(클래스명): 기존 클래스에 새로운 상태 변수 필드를 추가.

// REDscript 기반 기존 대미지 로직의 비파괴적 래핑 예시
@wrapMethod(PlayerPuppet)
protected cb func OnTakeDamage(damageEvent: ref[gameDamageReceivedEvent]) -> Bool {
    // 커스텀 선행 로직
    ModLog("대미지 감지: " + ToString(damageEvent.totalDamageReceived));
    
    // 원본 게임 로직 실행
    let result: Bool = wrappedMethod(damageEvent);
    
    // 커스텀 후행 로직
    return result;
}

3. ArchiveXL: 가상 파일 시스템 및 동적 에셋 마운팅

ArchiveXL이 개발되기 전에는 새로운 의상이나 무기를 추가하려면 기존 아이템의 3D 메시와 텍스처를 덮어써야만 했습니다. 따라서 같은 아이템을 교체하는 두 모드는 동시에 사용할 수 없었습니다.

동적 리소스 스트리밍

ArchiveXL은 RED4ext 플러그인으로 동작하며 REDengine의 리소스 로더(CResourceLoader)를 후킹합니다:

• 기존 .archive 파일을 수정하지 않고 가산형(Additive) 자원 등록을 구현합니다.
• 새로운 3D 모델, 텍스처, 리깅 파일은 독립된 .archive로 패키징되어 archive\pc\mod\ 폴더에 배치됩니다.
• 이와 함께 동일한 이름의 YAML 형식 메타데이터 파일(.xl)을 배치합니다(예: archive\pc\mod\MyCustomArmor.xl).

팩토리 인젝션 및 동적 모핑 지원

ArchiveXL은 .xl 명세서를 기반으로 다음 기능을 수행합니다:

• 게임 리소스 팩토리(resource.factories)에 신규 엔티티 템플릿을 동적으로 등록합니다.
• 동적 바디 모핑(Morphing)을 지원하여, 플레이어의 다양한 신체 체형 프리셋에 맞춰 의상이 늘어나거나 줄어들도록 조정해 클리핑(뚫림) 현상을 방지합니다.
• 다국어 로컬라이제이션 텍스트를 메모리에 동적 주입하여, 메인 언어 팩을 수정하지 않고도 아이템 이름과 툴팁을 여러 언어로 표시합니다.

4. TweakXL: 메모리 기반 TweakDB 데이터베이스 패치

REDengine 4에서 TweakDB는 무기 공격력, 방어구 방어력, 특전 계수, 제작 레시피, NPC 수치 등 모든 게임플레이 데이터를 관장하는 핵심 관계형 데이터베이스입니다.

바이너리 직접 덮어쓰기의 한계

바닐라 TweakDB는 r6\cache\tweakdb.bin 바이너리 파일로 직렬화되어 있습니다. 초창기 모드 도구들이 이 바이너리를 통째로 재생성하려 시도했으나, 이는 나중에 설치된 모드가 이전 모드의 모든 수정 사항을 덮어써 날려버리는 문제를 야기했습니다.

선언형 YAML 인메모리 주입

TweakXL은 TweakDB의 메모리 로딩 파이프라인을 가로채어 이 문제를 해결했습니다:

1. 엔진이 tweakdb.bin을 읽어 메모리에 올립니다.
2. TweakXL이 데이터베이스 초기화 포인터를 후킹합니다.
3. r6\tweaks\ 폴더 내 모든 .yaml 및 .tweak 파일을 파싱합니다.
4. 메모리상에서 기존 레코드를 복제(Clone)하거나 특정 필드 값을 수정하고, 새로운 고유 레코드를 추가합니다:

  # TweakXL YAML 선언을 통한 신규 무기 레코드 생성 예시
Items.MyCustomKatana:
  $type: gamedataItem_Record
  $base: Items.Preset_Katana_Default
  displayName: LocKey#MyCustomKatana_Name
  visualTags: [ "MyCustomKatana_Mesh" ]
  quality: Quality.Legendary
  statModifiers:
    - !append Items.BaseDamageModifier

이 메모리 패치 구조 덕분에 수백 개의 의상 및 장비 모드가 단 하나의 파일 충돌 없이 안전하게 공존할 수 있습니다.

모드 프레임워크 문제 해결 및 진단 매트릭스

모드 설치 후 《사이버펑크 2077》이 실행되지 않거나 오류가 발생할 경우 아래 매트릭스를 참조하여 진단하십시오:

PowerShell 자동 진단 스크립트: 프레임워크 무결성 및 로그 점검

모드 환경의 상태를 점검하고 오류 로그를 추출하려면 다음 PowerShell 명령을 실행하십시오:

  # 사이버펑크 2077 모드 프레임워크 환경 점검 스크립트
  param(
      [string]$GameRoot = "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077"
  )
  
  Write-Host "=== 사이버펑크 2077 모드 프레임워크 환경 점검 ===" -ForegroundColor Cyan
  
  # 1. 핵심 프레임워크 DLL 검증
  $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 "[정상] $name 확인됨 (버전: $version)" -ForegroundColor Green
      } else {
          Write-Host "[누락] $name 파일을 찾을 수 없음: $path" -ForegroundColor Red
      }
  }
  
  # 2. 최신 REDscript 컴파일 로그 점검
  $redscriptLog = "$GameRoot\r6\logs\redscript_rCURRENT.log"
  if (Test-Path $redscriptLog) {
      Write-Host "`nREDscript 컴파일 로그 점검 중..." -ForegroundColor Cyan
      $errors = Select-String -Path $redscriptLog -Pattern "ERROR", "FATAL" | Select-Object -First 5
      if ($errors) {
          Write-Host "[경고] REDscript 컴파일 오류가 감지되었습니다:" -ForegroundColor Yellow
          $errors | ForEach-Object { Write-Host "  " $_.Line -ForegroundColor Red }
      } else {
          Write-Host "[정상] 최신 컴파일 로그에 오류가 없습니다." -ForegroundColor Green
      }
  }

안정적인 모드 운영을 위한 권장 수칙

1. 버전 일치 준수: CD 프로젝트 레드가 패치를 배포할 때마다 메모리 오프셋이 바뀝니다. 패치 배포 직후에는 CET, RED4ext, ArchiveXL, TweakXL의 최신 릴리스가 나올 때까지 게임 업데이트를 일시 보류하거나 모드를 임시 비활성화해야 합니다.
2. 바닐라 Content 폴더 보존: archive\pc\content\ 폴더를 직접 변경하는 구형 모드는 지양하고, 모든 파일은 archive\pc\mod\, r6\, red4ext\ 규격 폴더에만 배치해야 합니다.
3. 무분별한 무결성 검사 자제: 게임 튕김 발생 시 Steam이나 GOG의 게임 무결성 검사를 바로 실행하면 커스텀 설정이 초기화될 수 있습니다. 먼저 r6\logs\ 및 red4ext\logs\를 열어 오류 모듈을 특정하십시오.
4. 시스템 아키텍처 원리에 기반한 모딩: 바이너리 후킹, 가상 파일 시스템, 인메모리 패치의 상호작용 원리를 체계적으로 이해하면 복잡한 대규모 모드 환경에서도 지속 가능한 게임 빌드를 유지할 수 있습니다. 365Finds와 같은 검증된 기술 지식 베이스를 참고하여 안정적이고 쾌적한 게이밍 경험을 구축하십시오.

참고 문헌

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