MetalFX Denoiser Mod - Agent Guidelines

Project Context

This mod replaces NVIDIA NRD (Real-time Denoisers) with Apple's MetalFX Temporal Scaler for Cyberpunk 2077 on macOS. It provides hardware-accelerated denoising for ray tracing features.

Current Status (Canonical)

See docs/STATUS.md and docs/DEVELOPMENT.md for the up-to-date project status and next steps.

Architecture

The mod consists of two shared libraries:

1. MetalFXDenoiser.dylib - RED4ext plugin (C++)

   • Entry point: src/plugin/main.cpp
   • NRD hooks: src/plugin/NRDHooks.cpp
   • Buffer extraction: src/plugin/BufferInterceptor.cpp
   • Configuration: src/plugin/Config.cpp

2. MetalFXDenoiserCore.dylib - Metal framework (Objective-C++)

   • C bridge: framework/MetalBridge.h
   • Denoiser wrapper: framework/MetalFXDenoiser.mm
   • Scaler pool: framework/TemporalScalerPool.mm
   • Buffer converter: framework/BufferConverter.mm

Key Addresses (Game v2.21)

Located in lib/Support/macOS/AddressResolverOverride.hpp:

Development

Building

mkdir build && cd build
cmake ..
make -j8

Updating Addresses

After game updates:

python3 scripts/discover_nrd_addresses.py

Testing

1. Copy dylibs to red4ext/plugins/MetalFXDenoiser/
2. Launch game via RED4ext
3. Check logs for hook activation

Current Status

• Address discovery complete
• Plugin infrastructure complete
• MetalFX wrapper complete
• Runtime hook installation (needs Frida)
• Buffer structure reverse engineering
• Integration testing

Code Standards

• C++20 for plugin code
• Objective-C++ for Metal framework
• Use std::cerr for logging (no spdlog dependency)
• Follow existing naming conventions