AGENTS.md

creation-engine-raytracing

Purpose

Ray-traced rendering extensions for Bethesda Creation Engine (Skyrim/Fallout 4). The project implements path tracing, hybrid global illumination, DXR ray tracing, GPU skinning, denoising, and supporting rendering infrastructure.

Repository Overview

Primary areas:

• src/Core/ — scene representation, meshes, BLAS/TLAS, materials, transforms.
• src/Pass/ — render passes (path tracing, GI, skinning, TLAS, NRD, utilities).
• src/Renderer/ — renderer and render-target management.
• src/Utils/ — traversal, adapters, shader compilation, helpers.
• shaders/ — HLSL shaders and shared include files.
• interop/ — C++/HLSL shared data layouts.

Core Architecture

Major systems:

• SceneGraph owns meshes, BLAS clusters, materials, transforms, GPU buffers, and per-frame scene updates.
• BaseMesh is the root mesh abstraction. Specialized mesh types handle static, skinned, dynamic, terrain LOD, and segmented geometry.
• BLASCluster groups meshes by game object and manages BLAS construction/refit plus TLAS instance generation.
• TransformManager uploads world transforms. Local transforms are composed on the GPU.
• MaterialManager owns the GPU material database and bindless material storage.

Read the implementation before modifying any subsystem.

Rendering Pipeline

Typical execution order:

Skinning → LandLODOccluder → TransformComposition → SceneTLAS → SHaRC → PathTracing or GlobalIllumination → NRD → Composite → Accumulation (PT)

Render passes live under src/Pass/.

Important Invariants

• Local mesh transforms are GPU-generated by Pass::TransformComposition. Do not move this back to the CPU.
• BLAS ownership is handled by BLASCluster.
• Segmented meshes produce one BLAS/TLAS instance per visible segment.
• Material data is stored in MaterialManager; avoid per-material GPU buffers.
• Preserve bindless descriptor stability whenever possible.
• Shared C++/HLSL layouts in interop/ must remain synchronized.

Shader Notes

• Shader compilation is centralized in src/Utils/Shader.cpp.
• DXR and RayQuery paths are both supported.
• Most behavior is controlled by compile-time defines generated by the shader utility code rather than hardcoded lists.

Development Guidelines

Before making changes:

1. Read the surrounding implementation.
2. Search for existing patterns.
3. Match existing architecture.
4. Preserve performance characteristics.
5. Minimize API changes.

Prefer extending existing systems instead of introducing parallel implementations.

Cross-Game Support

The codebase supports both Skyrim and Fallout 4.

When changing platform-specific code:

• keep both code paths functional
• follow existing #if defined(SKYRIM) / FALLOUT4 patterns
• avoid introducing behavior that only works on one game unless explicitly requested

Performance

Avoid:

• unnecessary allocations in hot paths
• redundant GPU uploads
• unnecessary BLAS rebuilds
• descriptor churn
• duplicate CPU/GPU state

Common Locations

• Scene management: src/SceneGraph.*
• BLAS: src/Core/BLASCluster.*
• Meshes: src/Core/Mesh/
• Materials: src/Core/Material*/
• Transform system: src/Core/TransformManager.*
• Shader compilation: src/Utils/Shader.cpp
• Shared shader data: interop/
• Ray tracing shaders: shaders/raytracing/

Agent Expectations

When implementing a task:

• understand the affected subsystem first
• preserve existing coding style
• avoid unrelated refactors
• explain architectural changes in commit messages or summaries
• verify assumptions against the source instead of this document

This file is intentionally concise. Use the source code as the primary documentation.